Como criar um aplicativo do Node.js

Como especificar versões do Node.js

O projeto de buildpacks fornece 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.

Como usar o package.json

É possível especificar a versão do Node.js do seu aplicativo durante a implantação, configurando o campo engines.node no package.json. Para configurar o buildpack e usar a versão mais recente do Node.js v16 ao implantar o app, use os valores a seguir no package.json:

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

Como usar o GOOGLE_NODEJS_VERSION

Também é possível especificar a versão do Node.js usando a variável de ambiente GOOGLE_NODEJS_VERSION. Se as duas configurações forem definidas, o valor GOOGLE_NODEJS_VERSION terá prioridade sobre a property engines.node. Se nenhum valor for fornecido, a versão LTS mais recente do Node.js será usada.

Para configurar o buildpack para usar o Node.js 16 ao implantar o app:

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

Também é possível usar um descritor de projeto project.toml para codificar a variável de ambiente com os arquivos do projeto. Veja instruções sobre como criar o aplicativo com variáveis de ambiente.

Dicas

  • O campo engines.node pode ter uma restrição semver. A biblioteca específica que usamos para os buildpacks do Node.js é Masterminds/semver.
  • Evite usar o especificador "maior que" (>) em engines.node.
  • Ao implantar o aplicativo no ambiente padrão do App Engine, a property engines.node precisa ser compatível com o ambiente de execução especificado em app.yaml.
  • A documentação adicional sobre a opção de configuração engines.node em package.json pode ser encontrada na documentação oficial do NPM no tópico sobre mecanismos.
  • Ao implantar uma função no Cloud Functions, a property engines.node precisa ser compatível com o ambiente de execução usado para implantar a função.

Como instalar dependências

usando npm:

  • O NPM é o gerenciador de pacotes padrão.
  • Sempre que possível, use package-lock.json para melhorar o desempenho do cache.
  • Por padrão, apenas as dependências de produção são instaladas.
  • É possível especificar a seção da versão do NPM usando o campo engines.npm no arquivo package.json.

usando yarn:

  • O Yarn é usado quando você inclui o arquivo yarn.lock no projeto.
  • É possível especificar a versão do Yarn a ser usada no campo engines.yarn do arquivo package.json.
  • O modo Yarn2 PnP será compatível se o projeto incluir um .yarn/cache.

usando pnpm:

  • O Pnpm é usado quando você inclui o arquivo pnpm-lock.yaml no projeto.
  • Você pode especificar uma versão do pnpm no campo engines.pnpm do seu arquivo package.json.
  • Para um exemplo prático, confira o app sample-node-pnpm.

Usar módulos privados

É possível usar um módulo npm particular. Para isso, basta fornecer configurações para autenticar com o registro em um arquivo .npmrc no diretório da função. Se você estiver usando o Yarn versão 2 ou mais recente como gerenciador de pacotes, esse arquivo será chamado de .yarnrc.yml.

Módulos particulares do Artifact Registry

Um repositório de pacotes Node.js do Artifact Registry pode hospedar módulos particulares para sua função. Quando você implanta uma função de buildpacks, o processo de build gera automaticamente credenciais do Artifact Registry para a conta de serviço do Cloud Build. Você só precisa listar o repositório do Artifact Registry no arquivo .npmrc ao usar o NPM ou o Yarn versão 1. Por exemplo, ao usar NPM ou 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 você estiver usando o Yarn versão 2 ou mais recente, basta listar o repositório do Artifact Registry no arquivo .yarnrc.yml sem credenciais adicionais. Exemplo:

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

Módulos particulares de outros repositórios

A documentação do npm explica como criar tokens personalizados de acesso somente leitura. Não recomendamos a utilização do arquivo .npmrc criado no diretório pessoal, porque ele contém um token de leitura/gravação. Permissões de gravação não são obrigatórias durante a implantação e podem representar um risco de segurança.

Não inclua o arquivo .npmrc se você não estiver usando repositórios particulares, porque isso pode aumentar o tempo de implantação de suas funções.

Formato do arquivo

Se você estiver usando um arquivo .npmrc para definir um token de autenticação personalizado, sera necessário que ele inclua a linha mostrada abaixo.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Substitua:

  • REGISTRY_DOMAIN: o nome de domínio do registro npm particular. Por exemplo, se o host do repositório for npmjs.org, defina esse campo como registry.npmjs.org.

  • AUTH_TOKEN: o token de autorização para o registro 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 relativo ao ambiente.

    É possível 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 mais detalhes do token de autenticação.

Como executar etapas de versão personalizadas durante a implantação

Por padrão, npm run build será executado se um script for especificado no arquivo package.json. No entanto, você pode especificar etapas personalizadas de versão para modificar o comportamento padrão e executar apenas os scripts que quiser durante a criação. É possível controlar as etapas de criação usando a variável de ambiente GOOGLE_NODE_RUN_SCRIPTS ou o gcp-build no arquivo package.json.

Só é possível usar um método. Observe que a variável de ambiente GOOGLE_NODE_RUN_SCRIPTS tem precedência e substitui tudo que é especificado para gcp-build em package.json.

Por padrão, quando você configura etapas de criação personalizadas, dependencies e devDependencies no arquivo package.json são instalados antes da execução de qualquer script ou comando. Para modificar o comportamento padrão, use a variável de ambiente NODE_ENV.

Como usar o GOOGLE_NODE_RUN_SCRIPTS

É possível transmitir a variável de ambiente GOOGLE_NODE_RUN_SCRIPTS para a versão a fim de controlar quais scripts são executados. É possível especificar um ou mais scripts ou transmitir uma variável de ambiente vazia para impedir a execução do comportamento padrão, como GOOGLE_NODE_RUN_SCRIPTS=. Para detalhes completos, consulte Variáveis de ambiente.

Como usar o package.json

A adição de gcp-build ao arquivo package.json executa apenas npm run gcp-build, o que significa que ele modifica o comportamento padrão. É possível especificar um ou mais comandos ou, em vez disso, especificar uma string vazia para impedir que qualquer comando seja executado, como "gcp-build":"".

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

Ponto de entrada do aplicativo

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

Recomendamos o uso de um Procfile porque ele remove npm ou yarn do caminho.

Variáveis de ambiente

É possível definir variáveis de ambiente para configurar versões da imagem do contêiner.

O buildpack do Node.js é compatível com as variáveis de ambiente a seguir para personalizar o contêiner.

NPM_CONFIG_<key>

Consulte a documentação.

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

NODE_ENV

Especifica o ambiente de desenvolvimento durante a compilação; definido para npm install.

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

GOOGLE_NODE_RUN_SCRIPTS

Especifica uma lista ordenada de scripts npm do package.json a ser executada após a instalação de dependências. A lista precisa ser separada por vírgulas e executada na ordem em que você lista cada script.

Quando você especifica GOOGLE_NODE_RUN_SCRIPTS, somente os scripts listados são executados. Por exemplo, se você quiser impedir a execução de npm run build padrão, especifique a variável de ambiente sem um valor.

Exemplos:

  • GOOGLE_NODE_RUN_SCRIPTS=lint,build executa npm run lint e depois npm run build.
  • GOOGLE_NODE_RUN_SCRIPTS= não executa scripts.