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. Você pode usar npm, yarn ou pnpm para instalar as dependências do Node.js.

O Functions Framework para Node.js é uma dependência necessária para todas as funções. Embora as funções do Cloud Run 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.

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')}!`);
});

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 comando a seguir 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 no 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: os pacotes npm estão disponíveis para vários produtos do Google Cloud . Consulte bibliotecas de cliente do Node.js.

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 build 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 um script gcp-build em package.json, as funções do Cloud Run apenas instalam 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.

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 uma função do Cloud Run Functions, 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 .npmrc sem gerar outras credenciais. 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 das 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, ele precisará incluir a seguinte linha.

//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 do token de autenticação.

Criar uma função com dependências copiadas

Dependências copiadas 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 copiadas do Node.js e pular a instalação delas durante a implantação.

Pré-requisitos para dependências copiadas

1. Verifique se você tem uma função ativa com todas as dependências que você quer copiar 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 copiadas com o seguinte comando:

     gcloud run deploy SERVICE \
       --source . \
       --function FUNCTION_ENTRY_POINT \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   Substitua:

   • SERVICE: o nome da função do Cloud Run que você está implantando.
   • FUNCTION_ENTRY_POINT: com o ponto de entrada da função no código-fonte.

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