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 do Cloud Functions geralmente são compatíveis com a instalação usando NPM ou yarn.

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

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');

// HTTP Cloud Function.
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

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. 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: o Cloud Functions instala 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.

Como configurar dependências de implantação

Como instalar dependências de produção com npm

Ao implantar a função, o Cloud Functions instala as dependências declaradas no arquivo package.json usando o comando npm install:

npm install --production

No ambiente de execução Node.js 8 e superior, se um arquivo yarn.lock existir, o Cloud Functions usará o comando yarn install:

yarn install --production

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, o Cloud Functions 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, o Cloud Functions apenas instalará 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.

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.

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.

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. Ao implantar no Cloud Functions, 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. Exemplo:

@SCOPE:registry=REPOSITORY_URL
//REPOSITORY_URL:always-auth=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 usar o arquivo .npmrc criado no diretório principal, 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, ele precisará incluir a linha mostrada abaixo. Substitua <YOUR_AUTH_TOKEN> pelo token de autenticação fornecido pelo NPM.

//registry.npmjs.org/:_authToken=<YOUR_AUTH_TOKEN>