Criar uma aplicação Node.js

Especificar versões do Node.js

O projeto buildpacks oferece suporte para as versões LTS atuais e ativas do Node.js. As versões mais antigas do Node.js estão disponíveis, mas podem não ser mantidas ativamente pelo projeto.

A usar package.json

Pode especificar a versão do Node.js da sua aplicação durante a implementação configurando o campo engines.node em package.json. Para configurar o buildpack de modo a usar a versão mais recente do Node.js v16 quando implementar a sua app, pode usar os seguintes valores no seu package.json:

"engines": {
  "node": "16.x.x"
}

A usar GOOGLE_NODEJS_VERSION

Também é possível especificar a versão do Node.js através da variável de ambiente GOOGLE_NODEJS_VERSION. Se ambas as configurações estiverem definidas, o valor GOOGLE_NODEJS_VERSION tem prioridade sobre a propriedade engines.node. Se não for indicado nenhum valor, é usada a versão LTS mais recente do Node.js

Para configurar o buildpack para usar o Node.js 16 quando implementar a sua app:

pack build --builder=gcr.io/buildpacks/builder \
   sample-functions-framework-node \
   --env GOOGLE_NODEJS_VERSION=16.x.x

Também pode usar um descritor de projeto project.toml para codificar a variável de ambiente juntamente com os ficheiros do projeto. Veja instruções sobre como criar a aplicação com variáveis de ambiente.

Dicas

  • O campo engines.node pode aceitar uma restrição semver. A biblioteca específica que usamos para os buildpacks do Node.js é Masterminds/semver
  • Evite usar especificadores de maior do que (>) em engines.node
  • Quando implementar a aplicação no ambiente padrão do App Engine, a propriedade engines.node deve ser compatível com o tempo de execução especificado em app.yaml
  • Pode encontrar documentação adicional acerca da opção de configuração engines.node em package.json na documentação oficial do NPM no tópico engines
  • Quando implementa uma função nas funções do Cloud Run, a propriedade engines.node deve ser compatível com o tempo de execução usado para implementar a sua função

Instalar dependências

Usar o NPM

  • O NPM é o gestor de pacotes predefinido.
  • Sempre que possível, use package-lock.json para melhorar o desempenho da cache.
  • Por predefinição, apenas são instaladas dependências de produção.
  • Pode especificar a secção da versão npm através do campo engines.npm no ficheiro package.json.

Usar o Yarn

  • O Yarn é usado quando inclui o ficheiro yarn.lock no seu projeto.
  • Pode especificar a versão do yarn a usar no campo engines.yarn do ficheiro package.json.
  • Suportamos o modo PnP do Yarn2 se o seu projeto incluir um .yarn/cache.

Usar o Pnpm

  • O Pnpm é usado quando inclui o ficheiro pnpm-lock.yaml no seu projeto.
  • Pode especificar uma versão do pnpm no campo engines.pnpm do ficheiro package.json.
  • Para um exemplo funcional, consulte a app sample-node-pnpm.

Usar módulos privados

Pode usar um módulo npm privado fornecendo definições para autenticação com o registo num ficheiro .npmrc no diretório da função. Se estiver a usar a versão 2 ou posterior do Yarn como gestor de pacotes, este ficheiro tem o nome .yarnrc.yml.

Módulos privados do Artifact Registry

Um repositório de pacotes do Node.js do Artifact Registry pode alojar módulos privados para a sua função. Quando implementa uma função de Buildpacks, o processo de compilação gera automaticamente credenciais do Artifact Registry para a conta de serviço do Cloud Build. Só tem de listar o repositório do Artifact Registry no ficheiro .npmrc quando usar o NPM ou o Yarn versão 1. Por exemplo, quando usa o NPM ou o Yarn versão 1:

@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

Se estiver a usar a versão 2 ou posterior do Yarn, só precisa de listar o repositório do Artifact Registry no ficheiro .yarnrc.yml sem credenciais adicionais. Por exemplo:

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

Módulos privados de outros repositórios

A documentação do npm explica como criar tokens de acesso personalizados de só de leitura. Desaconselhamos a utilização do ficheiro .npmrc criado no diretório inicial, uma vez que contém um token de leitura/escrita. As autorizações de escrita não são necessárias durante a implementação e podem representar um risco de segurança.

Não inclua o ficheiro .npmrc se não estiver a usar repositórios privados, uma vez que pode aumentar o tempo de implementação das suas funções.

Formato de ficheiro

Se estiver a usar um ficheiro .npmrc para definir um token de autorização personalizado, este deve incluir a linha apresentada abaixo.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Substituição:

  • REGISTRY_DOMAIN: o nome de domínio do seu registo npm privado. Por exemplo, se o anfitrião do repositório for npmjs.org, defina este campo como registry.npmjs.org.

  • AUTH_TOKEN: o token de autorização para o seu registo npm. Pode ser o valor de texto literal do token ou a string de texto${NPM_TOKEN}, que o comando npm substitui pelo valor real do token do ambiente.

    Pode definir a variável de ambiente $NPM_TOKEN com o argumento --set-build-env-vars para o comando gcloud functions deploy. Consulte o tutorial do NPM sobre módulos privados para ver mais detalhes do token de autorização do NPM.

Executar passos de compilação personalizados durante a implementação

Por predefinição, npm run build é executado se for especificado um script no seu ficheiro package.json. No entanto, pode especificar passos de compilação personalizados para substituir o comportamento predefinido e executar apenas os scripts que quer durante a compilação. Pode controlar os passos de compilação através da variável de ambiente GOOGLE_NODE_RUN_SCRIPTS ou de gcp-build no ficheiro package.json.

Só pode usar um método. Tenha em atenção que a variável de ambiente GOOGLE_NODE_RUN_SCRIPTS tem precedência e substitui tudo o que for especificado para gcp-build no seu package.json.

Por predefinição, quando configura passos de compilação personalizados, o dependencies e o devDependencies no ficheiro package.json são instalados primeiro antes de serem executados quaisquer scripts ou comandos. Para substituir o comportamento predefinido, pode usar a variável de ambiente NODE_ENV.

A usar GOOGLE_NODE_RUN_SCRIPTS

Pode transmitir a variável de ambiente GOOGLE_NODE_RUN_SCRIPTS à compilação para controlar que scripts são executados. Pode especificar um ou mais scripts ou, em alternativa, transmitir uma variável de ambiente vazia para impedir a execução do comportamento predefinido, como GOOGLE_NODE_RUN_SCRIPTS=. Para ver os detalhes completos, consulte o artigo Variáveis de ambiente.

A usar package.json

A adição de gcp-build no ficheiro package.json só executa npm run gcp-build, o que significa que substitui o comportamento predefinido. Pode especificar um ou mais comandos ou, em alternativa, especificar uma string vazia para impedir a execução de qualquer comando, como "gcp-build":"".

"scripts": {
  ...
  "gcp-build": "npm run lint && npm run build"
  ...
}

Ponto de entrada da aplicação

O buildpack do Node.js executa o comando especificado no campo scripts.start do seu package.json. Se scripts.start não estiver definido, o buildpack executa npm start.

Recomendamos que use um Procfile porque remove npm ou yarn do caminho.

Variáveis de ambiente

Pode definir variáveis de ambiente para configurar compilações da imagem do contentor.

O buildpack do Node.js suporta as seguintes variáveis de ambiente para personalizar o seu contentor.

NPM_CONFIG_<key>

Consulte a documentação.

Exemplo: NPM_CONFIG_FLAG=value transmite comandos -flag=value para npm.

NODE_ENV

Especifica o ambiente de programação durante a compilação; definido como npm install.

Exemplo: NODE_ENV=development instala dependencies e devDependencies especificados em package.json.

GOOGLE_NODE_RUN_SCRIPTS

Especifica uma lista ordenada de scripts npm de package.json a executar após a instalação de dependências. A lista tem de estar separada por vírgulas e é executada pela ordem em que cada script é apresentado.

Quando especifica GOOGLE_NODE_RUN_SCRIPTS, apenas são executados os scripts que indicar. Por exemplo, se quiser impedir a execução do npm run build predefinido, especifique a variável de ambiente sem um valor.

Exemplos:

  • GOOGLE_NODE_RUN_SCRIPTS=lint,build é executado npm run lint e, de seguida, npm run build.
  • GOOGLE_NODE_RUN_SCRIPTS= não executa scripts.