Criar um modelo personalizado

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O Firebase Studio oferece uma ampla variedade de modelos integrados que incluem todos os arquivos, pacotes do sistema (por exemplo, compiladores) e extensões de que você precisa para começar rapidamente com uma linguagem ou framework.

Também é possível iniciar um espaço de trabalho do Firebase Studio usando modelos da comunidade hospedados no GitHub. Para mais informações sobre como iniciar um novo espaço de trabalho usando um modelo, consulte Criar um espaço de trabalho do Firebase Studio.

A maioria dos usuários usa os modelos integrados ou importa projetos do Git, mas, para casos de uso mais avançados, é possível criar os próprios modelos:

• Se você for criar o próprio framework, biblioteca ou serviço, poderá deixar que os usuários comecem a usar sua tecnologia rapidamente sem sair do navegador, com todo o potencial de uma máquina virtual baseada na nuvem.

• Se você tiver uma pilha de tecnologia favorita para seus projetos, simplifique o processo de iniciar novos projetos com um modelo personalizado.

• Se você for ensinar outras pessoas, por exemplo, em um tutorial ou codelab, poderá remover algumas das etapas iniciais para os estudantes pré-configurando o ponto de partida do codelab como um modelo personalizado.

Depois de criar e testar o modelo personalizado, crie um link para ele e coloque-o no seu site, no arquivo README do repositório do Git, na página de detalhes do pacote (por exemplo, no NPM) ou em qualquer outro lugar em que você espera que os usuários comecem a usar sua tecnologia.

Pré-requisitos

Antes de começar:

• Saiba como usar o arquivo idx/dev.nix para personalizar seu ambiente.

• Conheça os conceitos básicos da linguagem Nix e mantenha a referência ao alcance.

Estrutura de arquivos do modelo

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

• idx-template.json inclui os metadados do modelo, contendo o nome, a descrição e os parâmetros visíveis para os usuários configurarem o modelo. Por exemplo, é possível permitir que os usuários escolham entre várias linguagens de programação ou casos de uso de exemplo. Firebase Studio usa essas informações para preparar a interface mostrada aos usuários quando eles escolhem criar um novo espaço de trabalho usando o modelo.

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

  1. Cria o diretório de trabalho para o novo espaço de trabalho.

  2. Configura o respectivo ambiente criando um arquivo .idx/dev.nix. Também é possível executar uma ferramenta de scaffolding de projeto, 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 Firebase Studio carregar o modelo.

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

Criar um modelo inicial

Para acelerar a criação de modelos, recomendamos que você comece com um dos seguintes métodos para criar um modelo do Firebase Studio que possa ser personalizado:

• Transformar qualquer repositório público do GitHub em um modelo
• Usar um modelo oficial ou da comunidade como base para seu modelo

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

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

• Não contém parâmetros configuráveis pelo usuário.
• Copia todos os arquivos do repositório de modelos (exceto os dois arquivos idx-template) para o espaço de trabalho do usuário. Já deve haver uma subpasta .idx com um arquivo dev.nix que define o ambiente.

Se você adicionar os arquivos a seguir a qualquer repositório público do GitHub (ou subpasta ou ramificação), ele será transformado em um modelo do Firebase Studio.

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/studio/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}
  '';
}

Consulte Personalizar seu modelo para saber mais sobre outras mudanças que podem ser feitas na personalização.

Criar um modelo personalizado usando um modelo oficial ou da comunidade

A equipe do Firebase Studio mantém dois repositórios para modelos do Firebase Studio:

• Modelos oficiais: são aqueles que você seleciona diretamente no painel do Firebase Studio ao criar um novo aplicativo.

• Modelos da comunidade: esses modelos permitem contribuições da comunidade de código aberto. Para usar um modelo da comunidade, clone o repositório de modelos da comunidade do Git. É possível usar o link completo do modelo que você quer usar.

Para criar um modelo personalizado com base em um modelo que já existe:

1. Decida qual modelo usar como base para o modelo personalizado e depois clone o projeto.

2. Personalize o idx-template.json, idx-template.nix e .idx/dev.nix conforme necessário, começando por Personalizar seu modelo.

3. Confira as mudanças no repositório.

4. Siga as etapas em Criar um novo espaço de trabalho para seu modelo para publicar e testar o modelo. Se você usar um repositório aninhado, vincule-o diretamente ao seu URL. Por exemplo, se você estivesse usando o modelo "Vanilla Vite" da comunidade, provisionaria e testaria um novo espaço de trabalho usando o seguinte URL:

   https://studio.firebase.google.com/new?template=https://github.com/project-idx/community-templates/tree/main/vite-vanilla
   

Consulte Personalizar seu modelo para saber mais sobre outras mudanças que podem ser feitas na personalização.

Personalizar seu modelo

Agora que você criou um modelo básico para desenvolver, é possível editar os arquivos idx-template.json, idx-template.nix e .idx/dev.nix conforme os seus requisitos. É possível personalizar outras configurações:

• Adicionar pacotes do sistema ao seu script bootstrap
• Adicionar parâmetros configuráveis pelo usuário
• Escolher quais arquivos precisam ser abertos por padrão
• Escolher um ícone de espaço de trabalho padrão

Usar outros pacotes do sistema no seu script bootstrap

O exemplo básico usa apenas comandos POSIX básicos para copiar arquivos para o lugar certo. O script bootstrap do modelo pode exigir a instalação de outros binários, como git, node, python3 ou outros.

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

Confira um exemplo de como adicionar o pkgs.nodejs, que contém 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"
  ''
}

Adicionar parâmetros configuráveis pelo usuário

Para permitir que os usuários personalizem o ponto de partida dos novos projetos deles, crie vários modelos ou um único modelo com parâmetros. Essa é uma ótima opção se os seus pontos de partida diferentes forem apenas valores diferentes transmitidos para uma ferramenta CLI (por exemplo, --language=js no lugar de --language=ts).

Para adicionar parâmetros, faça isto:

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

Descrever o parâmetro no idx-template.json

Confira um exemplo de como adicionar um parâmetro enum, que o Firebase Studio exibe como um menu suspenso ou um 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 renderizará um grupo de botões de opção para as duas opções e transmitirá o valor ts ou js para o script idx-template.nix.

Cada objeto de parâmetro tem as seguintes propriedades:

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

Depois de definir o objeto params no arquivo idx-template.json, é possível personalizar o script bootstrap 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 o ID language que seja um tipo enumerado com valores possíveis ts ou js, use-o conforme a seguir:

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

Escolher quais arquivos precisam ser abertos por padrão

É recomendável personalizar quais arquivos serão abertos para edição quando novos espaços de trabalho forem criados com seu modelo. Por exemplo, se o modelo for para um site básico, convém abrir os principais arquivos 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, conforme a seguir:

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

Escolher um ícone de espaço de trabalho padrão

É possível escolher o ícone padrão para os espaços de trabalho criados com seu modelo, colocando um arquivo PNG chamado icon.png ao lado do arquivo dev.nix, dentro do diretório .idx.

Testar seu modelo em um novo espaço de trabalho

A maneira mais simples de testar o 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 modelo:

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

É possível incluir uma ramificação e uma subpasta. Todos os links a seguir são válidos, desde que sejam 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 ou o URL que você vinculará ao botão "Abrir no Firebase Studio".

Compartilhar seu modelo

Depois de confirmar que o modelo se comporta conforme o 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 facilitar ainda mais a descoberta do modelo pelos usuários, adicione um botão "Abrir no Firebase Studio" ao README do site ou do repositório.