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 em funções do Cloud Run, 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 aplicativo 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ê usa o Yarn versão 2 ou mais recente como gerenciador de pacotes, o nome desse arquivo é .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ê usa o Yarn versão 2 ou mais recente, basta listar o repositório do Artifact Registry no arquivo .yarnrc.yml sem credenciais extras. Por 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.