Crea un modello personalizzato

IDX offre una vasta gamma di modelli integrati che includono tutti i file, i pacchetti di sistema (ad es. i compilatori) e le estensioni di cui un utente potrebbe avere bisogno per iniziare rapidamente a utilizzare un linguaggio o un framework.

Puoi anche creare modelli personalizzati configurabili dall'utente. Ad esempio:

• Se stai creando un framework, una libreria o un servizio personalizzato, puoi consentire agli utenti di iniziare rapidamente a utilizzare la tua tecnologia, senza abbandonare il browser, grazie a tutta la potenza di una macchina virtuale basata su cloud.

• Se disponi di uno stack tecnologico preferito per i tuoi progetti, puoi semplificare il processo di avvio di nuovi progetti con un modello personalizzato.

• Se stai insegnando ad altri, ad esempio attraverso un codelab, puoi rimuovere alcuni dei passaggi iniziali per gli studenti preconfigurando il punto di partenza per il codelab come modello personalizzato.

Quando hai a disposizione un modello personalizzato, puoi creare un link da inserire sul tuo sito web, nel file README del repository Git, nella pagina dei dettagli del pacchetto (ad es. in Gestione dei partner di rete) o in altre posizioni da cui gli utenti potrebbero voler iniziare a utilizzare la tua tecnologia.

Nota: puoi anche creare un link per consentire agli utenti di creare una nuova area di lavoro clonando un repository Git, che è meno configurabile rispetto alla creazione di un modello IDX, ma non richiede modifiche al repository Git.

Prerequisiti

Prima di iniziare, assicurati di acquisire familiarità con la personalizzazione del tuo ambiente con i file .idx/dev.nix.

I modelli utilizzano anche il linguaggio Nix, quindi potresti voler ripassare alcune nozioni di base o tenerlo a portata di mano come riferimento.

Struttura del file modello

Un modello è un repository GitHub pubblico (oppure una cartella o un ramo in un repository) contenente almeno due file:

• 

  Creazione di una nuova area di lavoro da un modello personalizzato

  idx-template.json include i metadati del modello, tra cui nome visibile all'utente, descrizione e parametri disponibili per consentire agli utenti di configurarlo. Ad esempio, puoi consentire agli utenti di scegliere tra una serie di linguaggi di programmazione o casi d'uso di esempio. IDX utilizza queste informazioni per preparare la UI mostrata agli utenti quando scelgono di creare una nuova area di lavoro dal tuo modello.

• idx-template.nix è un file scritto in lingua Nix che contiene uno script shell Bash (racchiuso in una funzione Nix) responsabile di:

  1. Creazione della directory di lavoro della nuova area di lavoro e
  2. È in corso la configurazione dell'ambiente mediante la creazione di un file .idx/dev.nix. Tieni presente che puoi anche eseguire semplicemente uno strumento di scaffolding del progetto come flutter create o npm init in questo script oppure eseguire uno script personalizzato scritto in Go, Python, Node.js o in un altro linguaggio.

  Questo file verrà eseguito con i parametri specificati dall'utente al momento della configurazione del modello.

Insieme a questi due file possono essere inclusi altri file, da utilizzare in idx-template.nix, per creare un'istanza del modello. Ad esempio, puoi includere il file .idx/dev.nix finale o persino includere tutti i file di scaffolding direttamente nel repository.

Un esempio di base: trasformare qualsiasi repository pubblico GitHub in un modello

Prima di entrare nel dettaglio della definizione di idx-template.json e idx-template.nix, è utile esaminare un modello di esempio di base che:

• Non ha parametri configurabili dall'utente
• Devi solo copiare tutti i file nel tuo repository di modelli (tranne i due file idx-template) nell'area di lavoro dell'utente. Dovrebbe essere già presente una sottocartella .idx con un file dev.nix che definisce l'ambiente.

L'aggiunta dei seguenti file a qualsiasi repository GitHub pubblico (o sottocartella o ramo) trasforma effettivamente il repository in un modello IDX.

idx-template.json

{
  "name": "Hello world",
  "description": "A template for a CLI program that prints 'hello world'",
  "icon": "https://www.gstatic.com/images/branding/productlogos/idx/v1/192px.svg",
  "params": []
}

idx-template.nix

# No user-configurable parameters
{ pkgs, ... }: {
  # Shell script that produces the final environment
  bootstrap = ''
    # Copy the folder containing the `idx-template` files to the final
    # project folder for the new workspace. ${./.} inserts the directory
    # of the checked-out Git folder containing this template.
    cp -rf ${./.} "$out"

    # Set some permissions
    chmod -R +w "$out"

    # Remove the template files themselves and any connection to the template's
    # Git repository
    rm -rf "$out/.git" "$out/idx-template".{nix,json}
  '';
}

Nota: oltre a $out, puoi ottenere l'ID della nuova area di lavoro anche utilizzando $WS_NAME.

Usa pacchetti di sistema aggiuntivi nello script bootstrap

L'esempio precedente utilizza solo i comandi POSIX di base per copiare i file nella posizione giusta. Lo script bootstrap del modello potrebbe richiedere l'installazione di programmi binari aggiuntivi, ad esempio git, node, python3 o altri.

Puoi rendere disponibili ulteriori pacchetti di sistema per il tuo script di bootstrap specificando packages nel file idx-template.nix, proprio come personalizzeresti un'area di lavoro con pacchetti di sistema aggiuntivi aggiungendo packages nel relativo file dev.nix.

Nota: idx-template.nix utilizza sempre il stable-23.11 canale Nix.

Ecco un esempio di aggiunta di pkgs.nodejs, che include programmi binari come node, npx e npm:

# idx-template.nix
{pkgs}: {
  packages = [
    # Enable "node", "npm" and "npx" in the bootstrap script below.
    # Note, this is NOT the list of packages available to the workspace once
    # it's created. Those go in .idx/dev.nix
    pkgs.nodejs
  ];

  bootstrap = ''
    mkdir "$out"
    # We can now use "npm"
    npm init --yes my-boot-strap@latest "$out"
  ''
}

Importante: lo script di bootstrap non può essere interattivo. Se attende l'input dell'utente, non verrà creata correttamente l'istanza del modello.

Aggiungi parametri configurabili dall'utente

Per consentire agli utenti di personalizzare il punto di partenza per il loro nuovo progetto, puoi creare più modelli o creare un singolo modello con parametri. Questa è un'ottima opzione se i diversi punti di partenza sono solo valori diversi trasferiti a uno strumento dell'interfaccia a riga di comando (ad esempio --language=js rispetto a --language=ts).

Per aggiungere parametri, devi:

1. Descrivi il parametro nell'oggetto params del file di metadati idx-template.json. IDX utilizza le informazioni contenute in questo file per preparare l'interfaccia utente (ad esempio caselle di controllo, menu a discesa e campi di testo) mostrata agli utenti del tuo modello.
2. Aggiorna il bootstrap idx-template.nix per utilizzare i valori selezionati dall'utente durante la creazione dell'istanza del modello.

Descrivi il tuo parametro in idx-template.json

Di seguito è riportato un esempio di aggiunta di un parametro enum, che IDX mostra sotto forma di menu a discesa o gruppo di pulsanti di opzione, a seconda del numero di opzioni.

{
  "name": "Hello world",
  "description": "A hello world app",
  "params": [
    {
      "id": "language",
      "name": "Programming Language",
      "type": "enum",
      "default": "ts",
      "options": {
        "js": "JavaScript",
        "ts": "TypeScript"
      },
      "required": true
    }
  ]
}

Poiché sono presenti due valori (JavaScript e TypeScript), l'interfaccia utente mostrerà un gruppo di pulsanti di opzione per le due opzioni e passerà il valore ts o js allo script idx-template.nix.

Ogni oggetto parametro ha le seguenti proprietà:

PROPRIETÀ	MACCHINA	DESCRIZIONE
ID	string	L'ID univoco del parametro, simile al nome di una variabile.
nome	string	Il nome visualizzato di questo parametro.
Tipo	string	Specifica il componente dell'interfaccia utente da utilizzare per questo parametro e il tipo di dati da passare allo script di bootstrap. I valori validi sono: "enum": mostra un gruppo di menu a discesa o di pulsanti di opzione e passa un string al bootstrap "boolean": mostra una casella di controllo e supera true o false "text": mostra un campo di testo e supera un string
opzioni del modello.	object	Per i parametri enum, rappresenta le opzioni da mostrare agli utenti. Ad esempio, se l'opzione è {"js": "JavaScript", ...}, l'opzione verrà visualizzata "JavaScript", mentre al momento della selezione il valore di questo parametro sarà js.
predefinita	string o boolean	Imposta il valore iniziale nell'interfaccia utente. Per i parametri enum, deve essere una delle chiavi in options. Per i parametri boolean, deve essere true o false.
di provisioning.	boolean	Indica che questo parametro è obbligatorio.

Utilizza i valori parametro in idx-template.nix

Dopo aver definito l'oggetto params nel file idx-template.json, puoi iniziare a personalizzare lo script di bootstrap in base ai valori parametro scelti dall'utente.

Seguendo l'esempio nella sezione precedente, se hai un singolo parametro con ID language che è un'enumerazione con possibili valori ts o js, puoi utilizzarlo in questo modo:

# idx-template.nix
# Accept additional arguments to this template corresponding to template
# parameter IDs, including default values (language=ts by default in this example).
{ pkgs, language ? "ts", ... }: {
  packages = [
    pkgs.nodejs
  ];

  bootstrap = ''
    # We use Nix string interpolation to pass the user's chosen programming
    # language to our script.
    npm init --yes my-boot-strap@latest "$out" -- --lang=${language}
  ''
}

Un altro pattern comune è includere contenuti in modo condizionale in base al valore di una stringa. Un altro modo per scrivere l'esempio precedente è:

npm init --yes my-boot-strap@latest "$out" -- \
    ${if language == "ts" then "--lang=ts" else "--lang=js" }

Importante: ricorda di produrre sempre un file .idx/dev.nix nella directory $out come parte dello script bootstrap. Se l'ambiente dell'area di lavoro generato deve variare in base a parametri configurati dall'utente (ad es. includendo diversi pacchetti di sistema o personalizzando l'hook onCreate), puoi utilizzare la manipolazione delle stringhe in Nix o richiamare un motore di modelli come jinja2.

Scegli quali file devono essere aperti per impostazione predefinita

È consigliabile personalizzare i file da aprire per la modifica quando vengono create nuove aree di lavoro con il modello. Ad esempio, se il modello è per un sito web di base, potresti voler aprire i file HTML, JavaScript e CSS principali.

Per personalizzare i file da aprire per impostazione predefinita, aggiorna il file .idx/dev.nix (non il file idx-template.nix) in modo da includere un hook area di lavoro onCreate con un attributo openFiles, in questo modo:

# .idx/dev.nix
{pkgs}: {
  ...
  idx = {
    # Workspace lifecycle hooks
    workspace = {
      # Runs when a workspace is first created with this `dev.nix` file
      onCreate = {
        # Open editors for the following files by default, if they exist.
        # The last file in the list will be focused.
        default.openFiles = [
          "src/index.css"
          "src/index.js"
          "src/index.html"
        ];
        # Include other scripts here, as needed, for example:
        # installDependencies = "npm install";
      };
      # To run something each time the workspace is (re)started, use the `onStart` hook
    };
    # Enable previews and customize configuration
    previews = { ... };
  };
}

Crea una nuova area di lavoro dal modello

Il modo più semplice per testare il tuo modello end-to-end è crearne una nuova area di lavoro. Visita il link seguente, sostituendo l'esempio con l'URL del repository GitHub del tuo modello:

https://idx.google.com/new?template=https://github.com/my-org/my-repo

Se vuoi, puoi includere un ramo e una sottocartella. Tutti i seguenti elementi sono validi, purché siano accessibili pubblicamente:

• https://github.com/my-org/my-repo/
• https://github.com/my-org/my-repo/tree/main/path/to/myidxtemplate
• https://github.com/my-org/my-repo/tree/branch
• https://github.com/my-org/my-repo/tree/branch/path/to/myidxtemplate

Questo è anche l'URL che condividerai con gli altri utenti in modo che possano utilizzare il tuo nuovo modello, oppure l'URL a cui collegherai gli utenti dal pulsante"Apri in IDX".

---

Condividi il modello

Dopo aver verificato che il modello funziona come previsto, pubblicalo in un repository GitHub e condividi lo stesso link utilizzato durante la creazione di un'area di lavoro per i test.

Per fare in modo che gli utenti trovino ancora più facilmente il tuo modello, aggiungi un pulsante"Apri in IDX" al file README del tuo sito web o del tuo repository.