Skip to main content
Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais atualizadas, acesse a documentação em inglês.

Como configurar um projeto Node.js para os GitHub Codespaces

Comece a executar um projeto Node.js, JavaScript ou TypeScript nos GitHub Codespaces criando uma configuração de contêiner de desenvolvimento personalizada.

Introdução

Este guia mostra como configurar um projeto Node.js de exemplo no GitHub Codespaces usando o cliente Web Visual Studio Code. Será descrito o processo de abertura do projeto em um codespace e da adição e da modificação de uma configuração de contêiner de desenvolvimento predefinido.

Depois de concluir este tutorial, você poderá adicionar uma configuração de contêiner de desenvolvimento ao seu repositório usando o cliente Web VS Code ou o aplicativo de área de trabalho VS Code.

Para obter mais informações sobre contêineres de desenvolvimento, confira "Introdução aos contêineres de desenvolvimento".

Etapa 1: abrir o projeto em um codespace

  1. Ir para https://github.com/microsoft/vscode-remote-try-node.

  2. Clique em Usar este modelo e, em seguida, em Abrir em um codespace.

    Captura de tela do botão 'Usar este modelo' e do menu suspenso

Ao criar um código, seu projeto será criado em uma máquina virtual remota dedicada a você. Por padrão, o contêiner para o seu código possui muitas linguagens e tempos de execução, incluindo Node.js, JavaScript e Typescript. Ele também inclui um conjunto comum de ferramentas, como nvm, npm, yarn, git, wget, rsync, openssh e nano.

Personalize seu codespace ajustando a quantidade de vCPUs e RAM, adicionando dotfiles para personalizar seu ambiente ou modificando as ferramentas e os scripts instalados. Para saber mais, confira "Como personalizar seu codespace".

Os GitHub Codespaces usam um arquivo chamado devcontainer.json para configurar o contêiner de desenvolvimento que é usado quando você trabalha em um codespace. Cada repositório pode conter um ou mais arquivos devcontainer.json, para fornecer exatamente o ambiente de desenvolvimento necessário para trabalhar em seu código em um codespace.

Na inicialização, os GitHub Codespaces usam um arquivo devcontainer.json e todos os arquivos dependentes que compõem a configuração do contêiner de desenvolvimento para instalar ferramentas e runtimes, além de executar outras tarefas de instalação necessárias para o projeto. Para obter mais informações, confira "Introdução aos contêineres de desenvolvimento". principal

Etapa 2: adicionar uma configuração de contêiner de desenvolvimento

O contêiner de desenvolvimento padrão, ou "contêiner de desenvolvimento," do GitHub Codespaces permitirá que você trabalhe com êxito em um projeto Node.js como vscode-remote-try-node. No entanto, recomendamos que você configure seu próprio contêiner de desenvolvimento para incluir todas as ferramentas e scripts necessários ao projeto. Isso garantirá um ambiente reprodutível para todos os usuários de GitHub Codespaces do seu repositório.

Para configurar seu repositório e usar um contêiner de desenvolvimento personalizado, você precisará criar um ou mais arquivos devcontainer.json. Você pode adicioná-los usando um modelo de configuração predefinido, no Visual Studio Code ou pode criar um. Para saber mais sobre contêineres de desenvolvimento, confira "Introdução aos contêineres de desenvolvimento". 1. Acesse a Visual Studio Code Command Palette (Shift+Command+P / Ctrl+Shift+P) e comece a digitar "contêiner de desenvolvimento". Clique em Codespaces: configurar o contêiner de desenvolvimento.

Captura de tela da opção "Codespaces: configurar o contêiner de desenvolvimento"

  1. Clique em Iniciar do zero.

    Captura de tela da opção "Iniciar do zero"

  2. Neste exemplo, o repositório de modelos com base no qual você criou o codespace já contém uma configuração de contêiner de desenvolvimento, portanto, uma mensagem é exibida informando que o arquivo de configuração já existe. Vamos substituir o arquivo de configuração existente, portanto, clique em Continuar.

  3. Clique em Mostrar todas as definições.

    Captura de tela da opção "Mostrar todas as definições"

  4. Digite node e clique em Node.js e JavaScript. Outras opções estarão disponíveis se o projeto usar ferramentas específicas. Por exemplo, Node e MongoDB.

    Captura de tela da opção 'Node.js e JavaScript'

  5. Escolha a versão do Node.js que você deseja usar para o projeto. Nesse caso, selecione a versão marcada como "(padrão)".

    Captura de tela da seleção de versão do Node.js

  6. Uma lista de recursos adicionais é exibida. Instalaremos o JSHint, uma ferramenta de qualidade de código para detectar erros no código JavaScript. Para instalar essa ferramenta, digite js, selecione JSHint (via npm) e clique em OK.

    Captura de tela de recursos adicionais para 'js'

  7. Uma mensagem é exibida informando que o arquivo de configuração do contêiner de desenvolvimento já existe. Clique em Substituir.

    Um arquivo devcontainer.json é criado e aberto no editor. ### Detalhes da configuração do contêiner de desenvolvimento personalizado

Se você examinar o Visual Studio Code Explorer, verá que um diretório .devcontainer foi adicionado à raiz do repositório do projeto que contém o arquivo devcontainer.json. Esse é o arquivo de configuração principal para codespaces criados com base nesse repositório.

devcontainer.json

O arquivo devcontainer.json que você adicionou conterá valores das propriedades name, image e features. Algumas propriedades adicionais que você pode considerar úteis estão incluídas, mas são comentadas.

O arquivo terá uma aparência semelhante a esta, dependendo de qual imagem você escolheu:

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/javascript-node
{
  "name": "Node.js",
  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
  "image": "mcr.microsoft.com/devcontainers/javascript-node:0-18-bullseye",
  "features": {
    "ghcr.io/devcontainers-contrib/features/jshint:2": {}
  }

  // Features to add to the dev container. More info: https://containers.dev/features.
  // "features": {},

  // Use 'forwardPorts' to make a list of ports inside the container available locally.
  // "forwardPorts": [],

  // Use 'postCreateCommand' to run commands after the container is created.
  // "postCreateCommand": "yarn install",

  // Configure tool-specific properties.
  // "customizations": {},

  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
  // "remoteUser": "root"
}
  • name: você pode nomear o contêiner de desenvolvimento como desejar. Um valor padrão é fornecido.
  • image: o nome de uma imagem em um registro de contêiner (DockerHub, GitHub Container registryou Registro de Contêiner do Azure) que será usado para criar o contêiner de desenvolvimento para o codespace.
  • features: uma lista de um ou mais objetos, cada um dos quais faz referência a um dos recursos de contêiner de desenvolvimento disponíveis. Os recursos são unidades autocontidas e compartilháveis de configuração do contêiner de desenvolvimento e do código de instalação. Eles proporcionam uma maneira fácil de adicionar mais ferramentas, runtime ou recursos de biblioteca ao seu contêiner de desenvolvimento. Para saber mais, confira "Recursos disponíveis de Contêiner de Desenvolvimento" no site de Contêineres de Desenvolvimento. Você pode adicionar recursos acessando VS Code Command Palette e digitando features.
  • forwardPorts: as portas listadas aqui serão encaminhadas automaticamente. Para obter mais informações, confira "Como encaminhar portas no seu codespace". - postCreateCommand: use esta propriedade para executar comandos após a criação do codespace.
  • customizations: esta propriedade permite personalizar uma ferramenta ou serviço específico quando usada para trabalhar em um codespace. Por exemplo, você pode definir configurações e extensões específicas para VS Code. Para saber mais, confira "Ferramentas e serviços de suporte" no site dos Contêineres de Desenvolvimento.
  • remoteUser: por padrão, você executa como o usuário vscode, mas, opcionalmente, pode definir isso como a raiz. Para ver uma lista completa das propriedades disponíveis, consulte a especificação de contêineres de desenvolvimento no site de Contêineres de Desenvolvimento.

Arquivos de configuração do contêiner de desenvolvimento adicionais

Se você estiver familiarizado com o Docker, talvez queira usar um Dockerfile, ou o Docker Compose, para configurar o ambiente de codespace, além do arquivo devcontainer.json. Você pode fazer isso adicionando seus arquivos Dockerfile ou docker-compose.yml ao lado do arquivo devcontainer.json. Para obter mais informações, confira "Como usar Imagens, Dockerfiles e Docker Compose" no site dos Contêineres de Desenvolvimento.

Etapa 3: Modifique seu arquivo devcontainer.json

Com as configurações do seu contêiner de desenvolvimento adicionadas e um entendimento básico do que tudo faz, agora você pode personalizar para configurar ainda mais o seu ambiente. Neste exemplo, você adicionará propriedades que:

  • Execute npm install, depois que o contêiner de desenvolvimento for criado, para instalar as dependências listadas no arquivo package.json.
  • Instalarão automaticamente uma extensão do VS Code neste codespace.
  1. No arquivo devcontainer.json, adicione uma vírgula após a propriedade features e exclua as duas linhas comentadas sobre os recursos.

    JSON
      "features": {
        "ghcr.io/devcontainers-contrib/features/jshint:2": {}
      },
    
      // Features to add to the dev container. More info: https://containers.dev/features.
      // "features": {},
  2. Remova a marca de comentário da propriedade postCreateCommand e atribua a ela o comando npm install.

    JSON
     // Use 'postCreateCommand' to run commands after the container is created.
     "postCreateCommand": "npm install",
  3. Remova a marca de comentário da propriedade customizations e edite-a conforme indicado a seguir para instalar a extensão "Verificador Ortográfico de Código" VS Code.

    JSON
    // Configure tool-specific properties.
    "customizations": {
      // Configure properties specific to VS Code.
      "vscode": {
        // Add the IDs of extensions you want installed when the container is created.
        "extensions": [
          "streetsidesoftware.code-spell-checker"
        ]
      }
    }

    O arquivo devcontainer.json agora deve ter uma aparência semelhante a esta, dependendo de qual imagem você escolheu:

    // README at: https://github.com/devcontainers/templates/tree/main/src/javascript-node
    {
      "name": "Node.js",
      // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
      "image": "mcr.microsoft.com/devcontainers/javascript-node:0-18-bullseye",
      "features": {
        "ghcr.io/devcontainers-contrib/features/jshint:2": {}
      },
    
      // Use 'forwardPorts' to make a list of ports inside the container available locally.
      // "forwardPorts": [],
    
      // Use 'postCreateCommand' to run commands after the container is created.
      "postCreateCommand": "npm install",
    
      // Configure tool-specific properties.
      "customizations": {
        // Configure properties specific to VS Code.
        "vscode": {
          // Add the IDs of extensions you want installed when the container is created.
          "extensions": [
            "streetsidesoftware.code-spell-checker"
          ]
        }
      }
    
      // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
      // "remoteUser": "root"
    }
    
  4. Salve suas alterações. 1. Acesse a VS Code Command Palette (Shift+Command+P / Ctrl+Shift+P) e comece a digitar "recompilar". Clique em Codespaces: Recompilar Contêiner.

    Captura de tela do comando Rebuild Container no Command Pallette

    Dica: ocasionalmente, convém executar uma recompilação completa para limpar o cache e recompilar o contêiner com imagens novas. Para obter mais informações, confira "Executar uma recompilação completa de um contêiner".

    A reconstrução dentro do seu codespace garante que as suas alterações funcionem conforme o esperado antes de realizar o commit das alterações no repositório. Se algo falhar, você será colocado em um codespace com um contêiner de recuperação que você pode reconstruir para continuar ajustando o seu contêiner.

    Depois que o contêiner de desenvolvimento for recriado, e o codespace ficar disponível novamente, o postCreateCommand terá sido executado, instalando o npm, e a extensão "Verificador Ortográfico de Código" estará disponível para uso.

Etapa 4: Execute seu aplicativo.

Na seção anterior, você usou o postCreateCommand para instalar um conjunto de pacotes por meio do comando npm install. Com as dependências agora instaladas, você pode executar o aplicativo.

  1. No Terminal do seu codespace, insira npm start.

    Captura de tela da execução de 'npm start' no terminal

  2. Quando o projeto for iniciado, você verá uma mensagem de notificação do sistema no canto inferior direito de VS Code, informando que seu aplicativo está disponível em uma porta encaminhada. Para exibir o aplicativo em execução, clique em Abrir no Navegador.

    Captura de tela da notificação do sistema de encaminhamento de porta

Etapa 5: Faça commit das suas alterações

Quando fizer alterações em seu código, tanto código novo quanto de configuração, você deverá fazer commit delas. O commit das alterações de configuração no repositório garante que qualquer pessoa que crie um codespace desse repositório tenha a mesma configuração. Qualquer personalização que você fizer, como adicionar extensões do VS Code, ficará disponível para todos os usuários.

Para este tutorial, você criou um codespace com base em um repositório de modelos, de modo que o código em seu codespace ainda não seja armazenado em um repositório. Você pode criar um repositório publicando o branch atual em GitHub.com.

Para obter informações, confira "Como usar o controle do código-fonte no seu codespace".

Próximas etapas

Agora você deve poder adicionar uma configuração de contêiner de desenvolvimento personalizada ao seu projeto Node.js, JavaScript ou TypeScript.

Aqui estão alguns recursos adicionais para cenários mais avançados.