Criar um modelo personalizado

O IDX oferece uma ampla variedade de modelos integrados que incluem todos os arquivos, pacotes do sistema (por exemplo, compiladores) e extensões que um usuário pode precisar para começar rapidamente a usar uma linguagem ou um framework.

Também é possível criar seus próprios modelos configuráveis pelo usuário. Exemplo:

• Se você estiver criando seu próprio framework, biblioteca ou serviço, poderá permitir que seus usuários comecem a usar sua tecnologia rapidamente, sem sair do navegador, com toda a capacidade de uma máquina virtual baseada na nuvem.

• Se você tiver uma pilha de tecnologia preferida para seus projetos, simplifique seu próprio processo para iniciar novos projetos com um modelo personalizado.

• Se você estiver ensinando outras pessoas, por exemplo, com um codelab, poderá remover algumas das etapas iniciais para os estudantes pré-configurando o ponto inicial do codelab como um modelo personalizado.

Quando seu modelo personalizado estiver pronto, crie um link para ele e coloque-o no seu site, arquivo README do repositório Git, na página de detalhes do pacote (por exemplo, em NPM) ou em outros lugares onde os usuários queiram começar a usar sua tecnologia.

Observação: também é possível criar um link para que os usuários criem um novo espaço de trabalho clonando um repositório Git, o que é menos configurável do que criar seu próprio modelo IDX, mas não exige mudanças no repositório Git.

Pré-requisitos

Antes de começar, familiarize-se com a personalização do seu ambiente com arquivos .idx/dev.nix.

Os modelos também usam a linguagem Nix (link em inglês). Portanto, convém revisar alguns dos princípios básicos ou mantê-los à mão como referência.

Modelo de estrutura de arquivos

Um modelo é um repositório público do GitHub (ou pasta ou ramificação em um repositório) que contém pelo menos dois arquivos:

• 

  Como criar um novo espaço de trabalho usando um modelo personalizado

  idx-template.json inclui os metadados do modelo, incluindo o nome visível ao usuário, a descrição e os parâmetros disponíveis para configurar o modelo. Por exemplo, você pode permitir que os usuários escolham entre várias linguagens de programação ou exemplos de casos de uso. O IDX usa essas informações para preparar a interface mostrada aos usuários quando eles decidem criar um novo espaço de trabalho usando seu modelo.

• idx-template.nix é um arquivo escrito com a linguagem Nix que contém um script de shell Bash (agrupado em uma função Nix) responsável por:

  1. Criar o diretório de trabalho do novo espaço de trabalho e
  2. Como configurar o ambiente criando um arquivo .idx/dev.nix. Observe que também é possível executar uma ferramenta de scaffolding de projetos como flutter create ou npm init nesse script ou executar um script personalizado escrito em Go, Python, Node.js ou outra linguagem.

  Esse arquivo será executado com os parâmetros especificados pelo usuário quando o modelo foi configurado.

Outros arquivos podem ser incluídos com esses dois arquivos, para uso em idx-template.nix, a fim de instanciar o modelo. Por exemplo, é possível incluir o arquivo .idx/dev.nix final ou até mesmo incluir todos os arquivos de scaffolding diretamente no repositório.

Um exemplo básico: transformar qualquer repositório público do GitHub em um modelo

Antes de entrar em detalhes sobre como definir idx-template.json e idx-template.nix, é útil ver um modelo básico de exemplo que:

• Não tem parâmetros configuráveis pelo usuário
• Apenas copia todos os arquivos no repositório de modelos (exceto os dois arquivos idx-template) para o espaço de trabalho do usuário. É necessário que já exista uma subpasta .idx com um arquivo dev.nix definindo o ambiente.

Adicionar os seguintes arquivos a qualquer repositório público do GitHub (ou subpasta ou ramificação) transforma esse repositório em um modelo 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}
  '';
}

Observação :além de $out, também é possível receber o ID do novo espaço de trabalho usando $WS_NAME.

Usar outros pacotes do sistema no script bootstrap

O exemplo anterior usa apenas comandos POSIX básicos para copiar arquivos no lugar certo. O script bootstrap do seu modelo pode exigir que outros binários sejam instalados, como git, node, python3 ou outros.

É possível disponibilizar outros pacotes do sistema para o script de inicialização especificando packages no arquivo idx-template.nix, assim como você personalizaria um espaço de trabalho com outros pacotes do sistema ao adicionar o packages no arquivo dev.nix.

Observação: idx-template.nix sempre usa o canal Nix stable-23.11.

Veja um exemplo de como adicionar pkgs.nodejs, que inclui binários como 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: o script de inicialização não pode ser interativo. Se aguardar a entrada do usuário, o modelo não será instanciado corretamente.

Adicionar parâmetros configuráveis pelo usuário

Para permitir que os usuários personalizem o ponto de partida do novo projeto, crie vários modelos ou crie um único modelo com parâmetros. Essa é uma ótima opção quando os diferentes pontos de partida são apenas valores diferentes transmitidos a uma ferramenta da CLI (por exemplo, --language=js versus --language=ts).

Para adicionar parâmetros, você vai:

1. Descreva o parâmetro no objeto params do arquivo de metadados idx-template.json. O IDX usa as informações nesse arquivo para preparar a IU (como caixas de seleção, menus suspensos e campos de texto) mostrada aos usuários do modelo.
2. Atualize o bootstrap da idx-template.nix para usar os valores selecionados pelo usuário ao instanciar o modelo.

Descreva o parâmetro em idx-template.json

Confira um exemplo de como adicionar um parâmetro enum, que o IDX mostra como um menu suspenso ou grupo de botões de opção, dependendo do número de opções:

{
  "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
    }
  ]
}

Como há dois valores (JavaScript e TypeScript), a interface renderiza um grupo de botões de opção para as duas opções e transmite o valor ts ou js para o script idx-template.nix.

Cada objeto de parâmetro tem as seguintes propriedades:

PROPRIEDADE	TIPO	DESCRIÇÃO
id	string	O ID exclusivo do parâmetro, semelhante a um nome de variável.
nome	string	O nome de exibição desse parâmetro.
Tipo	string	Especifica o componente de IU a ser usado para esse parâmetro e o tipo de dados a ser transmitido para o script de inicialização. Os valores válidos são: "enum": mostra um menu suspenso ou um grupo de botões de opção e transmite um string para o bootstrap. "boolean": mostra uma caixa de seleção e transmite true ou false. "text": mostra um campo de texto e transmite um string.
do modelo.	object	Para parâmetros enum, isso representa as opções para mostrar aos usuários. Por exemplo, se as opções forem {"js": "JavaScript", ...}, "JavaScript" será mostrado como a opção e, quando selecionado, o valor desse parâmetro será js.
default	string ou boolean	Define o valor inicial na interface. Para parâmetros enum, precisa ser uma das chaves em options. Para parâmetros boolean, precisa ser true ou false.
de provisionamento.	boolean	Indica que esse parâmetro é obrigatório.

Usar valores de parâmetro em idx-template.nix

Depois de definir o objeto params no arquivo idx-template.json, comece a personalizar o script de inicialização com base nos valores de parâmetro escolhidos pelo usuário.

Seguindo o exemplo na seção anterior, se você tiver um único parâmetro com ID language que seja uma enumeração com os possíveis valores ts ou js, poderá usá-lo da seguinte maneira:

# 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}
  ''
}

Outro padrão comum é incluir conteúdo condicionalmente, dependendo do valor de uma string. Outra maneira de escrever o exemplo anterior é:

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

Importante :lembre-se de sempre produzir um arquivo .idx/dev.nix no diretório $out como parte do script bootstrap. Se o ambiente de espaço de trabalho gerado precisar variar de acordo com os parâmetros configurados pelo usuário (por exemplo, incluir diferentes pacotes do sistema ou personalizar o gancho onCreate), você poderá usar a manipulação de string no Nix ou chamar um mecanismo de modelo como jinja2.

Escolher quais arquivos devem ser abertos por padrão

É uma boa ideia personalizar quais arquivos devem ser abertos para edição quando novos espaços de trabalho são criados com seu modelo. Por exemplo, se o modelo for para um site básico, convém abrir os arquivos principais HTML, JavaScript e CSS.

Para personalizar quais arquivos serão abertos por padrão, atualize o arquivo .idx/dev.nix (não o arquivo idx-template.nix) para incluir um hook de espaço de trabalho onCreate com um atributo openFiles, desta forma:

# .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 = { ... };
  };
}

Criar um novo espaço de trabalho com base no seu modelo

A maneira mais simples de testar seu modelo de ponta a ponta é criar um novo espaço de trabalho com ele. Acesse o link a seguir, substituindo o exemplo pelo URL do repositório do GitHub do seu modelo:

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

Também é possível incluir uma ramificação e uma subpasta. Todas as opções a seguir são válidas, desde que estejam acessíveis publicamente:

• 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

Esse também é o URL que você compartilhará com outras pessoas para que elas possam usar o novo modelo. Também é esse o URL que será vinculado ao botão "Abrir no IDX".

---

Compartilhar seu modelo

Depois de confirmar que seu modelo se comporta como esperado, publique-o em um repositório do GitHub e compartilhe o mesmo link usado ao criar um espaço de trabalho para testes.

Para que os usuários encontrem seu modelo ainda mais facilmente, adicione um botão"Abrir no IDX" ao README do seu site ou repositório.