Especificar dependências no Node.js

Uma função pode usar módulos Node.js externos, bem como dados locais. Dependências no Node.js são gerenciadas com npm e expressas em um arquivo de metadados chamado package.json. Os ambientes de execução Node.js das funções do Cloud Run são compatíveis com a instalação usando npm, yarn ou pnpm.

Para especificar uma dependência para sua função, adicione-a ao seu arquivo package.json.

Observação: se um arquivo package-lock.json, yarn.lock ou pnpm-lock.yaml for encontrado no projeto, esse arquivo de bloqueio será respeitado quando as dependências forem instaladas usando npm ci, yarn install ou pnpm install.

Neste exemplo, uma dependência é listada no arquivo package.json:

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

Em seguida, a dependência é importada na função:

const functions = require('@google-cloud/functions-framework');
const escapeHtml = require('escape-html');

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

O Functions Framework é uma dependência necessária para todas as funções. Embora as funções do Cloud Functions o instalem em seu nome quando a função é criada, recomendamos que você a inclua como uma dependência explícita para maior clareza.

Se a função depende de dependências particulares, recomendamos que você espelhe functions-framework no registro particular. Inclua o functions-framework espelhado como uma dependência da sua função para evitar a instalação do pacote pela Internet pública.

Como usar npm para instalar os módulos Node.js localmente

A maneira mais fácil de instalar um módulo Node.js localmente é usar o comando npm install na pasta que contém a função do Cloud Run. Por exemplo, o seguinte comando adiciona o módulo uuid:

npm install uuid

Esse processo combina duas etapas:

1. Ele marca a versão mais recente do módulo como uma dependência em seu arquivo package.json. Importante: as funções do Cloud Run instalam apenas módulos que são declarados em seu arquivo package.json.
2. Ele faz o download do módulo no diretório node_modules. Isso permite que você use o módulo ao desenvolver localmente.

Se você não tiver o NPM instalado na sua máquina, faça o download aqui.

Observação: pacotes npm estão disponíveis para vários produtos do Google Cloud. Confira a lista aqui.

Como configurar dependências de implantação

É possível instalar dependências de produção para NPM, Yarn ou Pnpm:

NPM

Ao implantar a função, as funções do Cloud Run instalam as dependências declaradas no arquivo package.json usando o comando npm install:

npm install --production

Yarn

No ambiente de execução Node.js 8 e superior, se um arquivo yarn.lock existir, as funções do Cloud Run usarão o comando yarn install:

yarn install --production

Pnpm

No ambiente de execução Node.js 8 e superior, se um arquivo pnpm-lock.yaml existir, as funções do Cloud Run usarão o comando pnpm install:

pnpm install

Observação: dependências declaradas em subdiretórios não são instaladas. Se você estiver usando um monorepo, execute um script de compilação personalizado durante a implantação para instalar essas dependências.

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

Depois de implantar, é possível executar uma etapa de compilação personalizada durante o processo de compilação da função adicionando um gcp-buildscript no arquivo package.json.

Ao executar este script, as dependências nos campos dependencies e devDependencies do arquivo package.json estarão disponíveis. Após a execução da etapa de versão personalizada, as funções do Cloud Run removerá e regenerará a pasta node_modules instalando apenas as dependências de produção declaradas no campo dependencies do seu arquivo package.json.

Se não houver script gcp-build em package.json, as funções do Cloud Run apenas instalarão as dependências de produção.

Como usar pacotes do sistema

O ambiente de execução Node.js também inclui vários pacotes do sistema no ambiente de execução. Se a função usar uma dependência que exija um pacote que não esteja listado, será possível solicitá-lo.

Observação: também é possível implantar versões em contêiner da função do Cloud Run do Node.js no Cloud Run usando o Functions Framework.

Como incluir módulos Node.js locais

Também é possível incluir módulos Node.js como parte da sua função. Para isso, declare seu módulo em package.json usando o prefixo file:. No exemplo a seguir, mymodule se refere ao nome do seu módulo, e mymoduledir é o diretório que contém o módulo:

{
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}

O código desse módulo local precisa ser armazenado em algum lugar diferente da pasta node_modules no diretório raiz da função.

Observação: se você implantar usando a ferramenta de linha de comando gcloud, gcloud cria automaticamente um arquivo .gcloudignore no diretório da sua função. Por padrão, a pasta node_modules é adicionada a esta .gcloudignore e não é enviada como parte de sua implantação. Não é necessário incluir a pasta node_modules ao fazer o upload manual do código como um arquivo ZIP. É possível implantar a função sem a pasta node_modules.

Carregar módulos Node.js

Use a função require() do Node.js para carregar qualquer módulo Node.js que tiver instalado. Também é possível usar a função require() para importar os arquivos locais implantados com sua função.

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 v2 ou versão 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 as funções do Cloud Run, o processo de compilação 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 .npmrc sem gerar outras credenciais. Por exemplo:

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

Essa abordagem também funciona para o gerenciador de pacotes Yarn v1. Se você estiver usando o Yarn v2 ou mais recente, basta listar o repositório do Artifact Registry no .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.

Observação: se você estiver usando permissões personalizadas (como as necessárias para VPC), permita que as funções acessem o repositório particular de destino.

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. Se o repositório estiver hospedado em 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 npm substitui pelo valor real do token do 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 sobre o token de autenticação do NPM.

Criar uma função com dependências disponibilizadas por pacotes de terceiros

Dependências disponibilizadas por pacotes de terceiros são aquelas em que a origem é incluída diretamente no pacote de código-fonte e recriada com seu próprio código. Use a variável de ambiente de build GOOGLE_VENDOR_NPM_DEPENDENCIES para criar dependências do Node.js disponibilizadas por pacotes de terceiros e pular a instalação delas durante a implantação.

Pré-requisitos para dependências disponibilizadas por pacotes de terceiros

1. Verifique se você tem uma função ativa com todas as dependências que você quer que sejam definidas pelo fornecedor no arquivo package.json.

2. Instale essas dependências localmente executando:

       npm install
   

3. Remova node_modules do arquivo .gcloudignore no diretório de trabalho.

4. Implante a função, garantindo que a versão do Node.js local seja a mesma especificada durante a implantação.

5. Implante a função e as dependências disponibilizadas por pacotes de terceiros com o seguinte comando:

     gcloud functions deploy FUNCTION_NAME \
       --runtime RUNTIME_NAME \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   Substitua:

   • FUNCTION_NAME: o nome da função das funções do Cloud Run que você está implantando.
   • RUNTIME_NAME: o nome do ambiente de execução do Node.js para executar a função implantada. Precisa ser a mesma versão do Node.js usada no ambiente de desenvolvimento local.

O pacote do framework do Functions é uma dependência necessária para funções. Para builds mais rápidos, recomendamos a disponibilização de pacotes de terceiros. Caso contrário, ele será transferido por download e instalado quando a função for criada.

Se você especificar um mecanismo NPM no arquivo package.json, será feito o download da versão especificada do NPM no tempo de build. Para suprimir esse comportamento, remova-o do arquivo package.json.