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, pnpm ou Bun para instalar 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.

Se o buildpack do Node.js detectar um arquivo de bloqueio, como package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock ou bun.lockb no seu projeto, ele vai priorizar esse arquivo ao instalar dependências usando npm ci, yarn install, pnpm install ou bun install.

O exemplo a seguir lista uma dependência no arquivo package.json:

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

O Cloud Run importa a dependência 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')}!`);
});

Use npm para instalar 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.

Configurar dependências de implantação

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

Gerenciador de pacotes 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

Gerenciador de pacotes 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

Gerenciador de pacotes 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

Gerenciador de pacotes do Bun

Pré-lançamento — Support for the Bun package manager

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

O buildpack do Node.js é compatível com o gerenciador de pacotes do Bun. Com o gerenciador de pacotes Bun, é possível instalar dependências e manter a estrutura e a versão de tempo de execução do projeto Node.js. Você pode escolher qualquer um dos seguintes mecanismos para instalar dependências usando o Bun:

• Detecção automática: o buildpack do Node.js detecta o gerenciador de pacotes do Bun quando você inclui um arquivo bun.lock ou bun.lockb no projeto. Para configurar a detecção automática com o Bun, siga estas etapas:

  1. Crie o arquivo de bloqueio:

     bun install --lockfile-only
     

  2. Implante no Cloud Run executando o seguinte comando:

      gcloud run deploy --source . --base-image=nodejs24
     

• Aceitação explícita: defina a variável de ambiente GOOGLE_PACKAGE_MANAGER como bun. Com esse método, não é necessário criar e manter arquivos de bloqueio. Execute o seguinte comando para implantar no Cloud Run:

  gcloud run deploy --source . --base-image=nodejs24 --set-build-env-vars GOOGLE_PACKAGE_MANAGER=bun
  

Embora o buildpack use o Bun para instalar dependências, o ambiente de execução do Node.js ainda executa o aplicativo. Seu projeto precisa incluir um arquivo package.json. Para mais detalhes sobre os requisitos de configuração, consulte Como criar um aplicativo Node.js na documentação dos buildpacks.

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 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 fornecendo 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.