Criar e testar aplicativos Node.js

Nesta página, explicamos como usar o Cloud Build para criar e testar aplicativos Node.js, armazenar artefatos criados em um repositório npm no Artifact Registry e gerar informações de procedência da versão.

O Cloud Build permite que você use qualquer imagem de contêiner disponível publicamente para executar suas tarefas. A imagem pública node do Docker Hub vem pré-instalada com a ferramenta npm. É possível configurar o Cloud Build para criar seu projeto Node.js com essa ferramenta.

Antes de começar

Nas instruções desta página, pressupomos que você está familiarizado com Node.js. Além disso:

Criando com o npm

Para executar suas tarefas na imagem node do Docker Hub, especifique o URL da imagem no campo name no arquivo de configuração do Cloud Build. O Cloud Build inicia o contêiner especificado no campo name usando o ponto de entrada padrão da imagem. Para substituir o ponto de entrada padrão e definir como executar a etapa de build quando ela for invocada, adicione um campo entrypoint na etapa de build. A imagem node no Docker Hub vem pré-instalada com a ferramenta npm. Especifique as ferramentas no campo entrypoint para invocá-las como o ponto de entrada da etapa de build.

No seguinte arquivo de configuração de build de exemplo:

  • O campo name especifica que a imagem node do Docker Hub é usada pelo Cloud Build para executar a tarefa. Ao especificar a imagem node, é possível omitir a versão do nó como padrão para :latest ou especificar uma versão do nó para usar uma versão específica. Por exemplo, name: node usará a versão mais recente do nó e name: node:12 usará node:12.
  • O campo entrypoint especifica que a ferramenta npm é usada quando a imagem node é invocada.

     steps:
     - name: 'node'
       entrypoint: 'npm'
    

Como configurar builds Node.js

  1. No diretório raiz do projeto, crie um arquivo de configuração chamado cloudbuild.yaml.

  2. Instalar dependências: antes de criar seu aplicativo, é necessário garantir que todas as dependências do projeto sejam instaladas a partir do npm. Você pode instalar dependências usando o comando install na etapa de criação npm. O campo args de uma etapa de build recebe uma lista de argumentos e os transmite para a imagem referenciada pelo campo de nome. No arquivo de configuração da versão, adicione install ao campo args para invocar o comando install:

     steps:
     - name: 'node'
       entrypoint: 'npm'
       args: ['install']
    
  3. Adicionar testes: se você tiver definido um script test em package.json, adicione test ao campo args para que Cloud Build execute o script:

     steps:
     - name: 'node'
       entrypoint: 'npm'
       args: ['install']
     - name: 'node'
       entrypoint: 'npm'
       args: ['test']
    
  4. Executar comandos personalizados: se package.json tiver comandos personalizados, configure o Cloud Build para executar esse comando. No campo args, adicione run como o primeiro argumento seguido pelo nome do comando personalizado. O arquivo de configuração da versão a seguir tem argumentos para executar um comando personalizado chamado build:

     steps:
     - name: 'node'
        entrypoint: 'npm'
        args: ['install']
     - name: 'node'
        entrypoint: 'npm'
        args: ['test']
     - name: 'node'
        entrypoint: 'npm'
        args: ['run', 'build']
    
  5. Faça upload para o Artifact Registry:

    O Cloud Build gera informações de procedência do build em Supply Chain Levels for Software Artifacts (SLSA) para pacotes npm independentes quando você faz upload deles para o Artifact Registry usando o campo npmPackages no arquivo de configuração do Cloud Build.

    No arquivo de configuração, adicione o campo npmPackages e especifique o repositório npm no Artifact Registry:

     artifacts:
        npmPackages:
        - repository: 'https://LOCATION-npm.pkg.dev/PROJECT-ID/REPOSITORY_NAME'
          packagePath: 'PACKAGE_PATH'
    

    Substitua os seguintes valores:

    • LOCATION: o local do repositório no Artifact Registry.
    • PROJECT_ID: o ID do projeto do Google Cloud que contém o repositório do Artifact Registry.
    • REPOSITORY_NAME: o nome do repositório npm no Artifact Registry.
    • PACKAGE_PATH: o caminho do diretório local que contém o pacote npm que você quer enviar para o Artifact Registry. Recomendamos o uso de um caminho absoluto. Seu valor PACKAGE_PATH pode ser . para usar o diretório de trabalho atual, mas o campo não pode ser omitido ou deixado em branco. Esse diretório precisa conter um arquivo package.json.
  6. Opcional: ativar a procedência para builds regionais

    Se você estiver usando um build regional, adicione o campo requestedVerifyOption no options no arquivo de configuração do build. Defina o valor como VERIFIED para ativar a geração de metadados de procedência. Se você não adicionar requestedVerifyOption: VERIFIED, o Cloud Build vai gerar procedência apenas para builds globais.

    options:
      requestedVerifyOption: VERIFIED
    
  7. Iniciar seu build: manualmente ou usando gatilhos de compilação.

    Quando o build for concluído, será possível acessar os detalhes do repositório no Artifact Registry.

    Também é possível conferir os metadados de procedência do build e a validação para ajudar a proteger sua cadeia de suprimentos de software.

Como executar testes em várias versões de node

Às vezes, é necessário garantir que o projeto funcione em várias versões de node. É possível criar e configurar gatilhos do Cloud Build de maneira que:

  • No arquivo de configuração de build, especifique a versão node como uma variável de substituição.
  • Crie um gatilho para cada versão de node usada como referência durante a compilação no aplicativo.
  • Em cada uma das configurações do gatilho, use o campo de valor da variável de substituição para indicar a versão de node para o gatilho.

As etapas a seguir explicam como especificar a versão de node usando variáveis de substituição específicas do gatilho:

  1. Na raiz do repositório, adicione um arquivo de configuração do build, que especifica a versão de node como uma variável de substituição. No exemplo de arquivo de configuração do build a seguir, $_NODE_VERSION é uma variável de substituição definida pelo usuário:

     steps:
     - name: 'node:$_NODE_VERSION'
       entrypoint: 'npm'
       args: ['install']
     - name: 'node:$_NODE_VERSION'
       entrypoint: 'npm'
       args: ['test']
    
  2. Para cada versão de node que você quer usar como base, crie um gatilho de compilação seguindo estas etapas:

    1. Abra a página Gatilhos no Console do Google Cloud:

      Abrir a página "Gatilhos"

    2. Selecione o projeto no menu suspenso do seletor de projetos na parte superior da página.

    3. Clique em Abrir.

    4. Clique em Criar gatilho.

      Na página Criar gatilho, especifique as seguintes configurações:

      1. Insira um nome para o gatilho.

      2. Selecione o evento de repositório para iniciar o gatilho.

      3. Selecione o repositório que contém o código-fonte e o arquivo de configuração de build.

      4. Especifique o regex do nome da ramificação ou da tag que iniciará o gatilho.

      5. Configuração: escolha o arquivo de configuração da compilação que você criou anteriormente.

      6. Em Variáveis de substituição, clique em Adicionar variável.

        1. Em Variável, especifique a variável de versão node usada no arquivo de configuração do build. Em Valor, especifique a versão do node. Por exemplo, _NODE_VERSION e 12.
    5. Clique em Criar para salvar o gatilho de build.

Use esses gatilhos para criar seu código na versão de node especificada no gatilho.

A seguir