Especificar dependencias en Node.js

Una función puede usar módulos Node.js externos, así como datos locales. Las dependencias de Node.js se gestionan con npm y se expresan en un archivo de metadatos llamado package.json. Puedes usar npm, yarn o pnpm para instalar las dependencias de Node.js.

El Functions Framework de Node.js es una dependencia obligatoria para todas las funciones. Aunque Cloud Run Functions lo instala en tu nombre cuando se crea la función, te recomendamos que lo incluyas como dependencia explícita para mayor claridad.

Si tu función depende de dependencias privadas, te recomendamos que hagas una réplica de functions-framework en tu registro privado. Incluye functions-framework como dependencia de tu función para evitar instalar el paquete desde Internet.

Para especificar una dependencia de tu función, añádela al archivo package.json.

Nota: Si se encuentra un archivo package-lock.json, yarn.lock o pnpm-lock.yaml en tu proyecto, se respetará ese archivo de bloqueo cuando se instalen las dependencias con npm ci, yarn install o pnpm install.

En este ejemplo, se muestra una dependencia en el archivo package.json:

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

A continuación, la dependencia se importa en la función:

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

Usar npm para instalar módulos de Node.js de forma local

La forma más sencilla de instalar un módulo de Node.js de forma local es usar el comando npm install en la carpeta que contiene tu función de Cloud Run. Por ejemplo, el siguiente comando añade el módulo uuid:

npm install uuid

De esta forma, se combinan dos pasos:

1. Marca la última versión del módulo como dependencia en el archivo package.json. Esto es muy importante: Cloud Run Functions solo instala los módulos que se declaran en el archivo package.json.
2. Descarga el módulo en tu directorio node_modules. De esta forma, podrás usar el módulo cuando desarrolles de forma local.

Si no tienes npm instalado en tu máquina, descarga npm.

Nota: Los paquetes npm están disponibles para varios Google Cloud productos. Consulta las bibliotecas de cliente de Node.js.

Configurar dependencias de despliegue

Puedes instalar dependencias de producción para NPM, Yarn o Pnpm:

NPM

Cuando despliegues tu función, Cloud Run Functions instalará las dependencias declaradas en el archivo package.json con el comando npm install:

npm install --production

Lana

En el tiempo de ejecución de Node.js 8 y versiones posteriores, si existe un archivo yarn.lock, Cloud Run Functions usa el comando yarn install:

yarn install --production

Pnpm

En el tiempo de ejecución de Node.js 8 y versiones posteriores, si existe un archivo pnpm-lock.yaml, Cloud Run Functions usa el comando pnpm install:

pnpm install

Nota: No se instalan las dependencias declaradas en subdirectorios. Si usas un monorrepositorio, puede que quieras ejecutar una secuencia de comandos de compilación personalizada durante la implementación para instalar esas dependencias.

Ejecutar pasos de compilación personalizados durante la implementación

Después de la implementación, puedes realizar un paso de compilación personalizado durante el proceso de compilación de la función añadiendo una secuencia de comandos gcp-build en el archivo package.json.

Cuando se ejecuta esta secuencia de comandos, las dependencias de los campos dependencies y devDependencies de tu archivo package.json están disponibles. Después de ejecutar el paso de compilación personalizado, las funciones de Cloud Run eliminan y vuelven a generar la carpeta node_modules instalando solo las dependencias de producción declaradas en el campo dependencies del archivo package.json.

Si no hay ningún script gcp-build en package.json, las funciones de Cloud Run solo instalan las dependencias de producción.

Usar paquetes del sistema

El tiempo de ejecución de Node.js también incluye varios paquetes del sistema en el entorno de ejecución.

Incluir módulos locales de Node.js

También puedes incluir módulos locales de Node.js como parte de tu función. Para ello, declara tu módulo en package.json con el prefijo file:. En el ejemplo siguiente, mymodule hace referencia al nombre del módulo y mymoduledir es el directorio que contiene el módulo:

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

El código de este módulo local debe almacenarse en un lugar que no sea la carpeta node_modules del directorio raíz de tu función.

Nota: Si realizas la implementación con la herramienta de línea de comandos gcloud, esta creará automáticamente un archivo .gcloudignore en el directorio de tu función.gcloud De forma predeterminada, la carpeta node_modules se añade a este .gcloudignore y no se sube como parte de tu implementación. No es necesario que incluyas la carpeta node_modules cuando subas manualmente el código como archivo ZIP. Puedes desplegar tu función correctamente sin la carpeta node_modules.

Cargar módulos de Node.js

Usa la función Node.js require() para cargar cualquier módulo de Node.js que hayas instalado. También puedes usar la función require() para importar archivos locales que despliegues junto con tu función.

Usar módulos privados

Puedes usar un módulo npm privado proporcionando ajustes para autenticarte con el registro en un archivo .npmrc del directorio de la función. Si usas Yarn v2 o una versión posterior como gestor de paquetes, este archivo se llama .yarnrc.yml.

Módulos privados de Artifact Registry

Un repositorio de paquetes de Node.js de Artifact Registry puede alojar módulos privados para tu función. Cuando despliegas una función de Cloud Run Functions, el proceso de compilación genera automáticamente credenciales de Artifact Registry para la cuenta de servicio de Cloud Build. Solo tienes que incluir el repositorio de Artifact Registry en tu .npmrc sin generar credenciales adicionales. Por ejemplo:

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

Este enfoque también funciona con el gestor de paquetes Yarn v1. Si usas Yarn v2 o una versión posterior, solo tienes que incluir el repositorio de Artifact Registry en tu .yarnrc.yml sin credenciales adicionales. Por ejemplo:

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

Módulos privados de otros repositorios

En la documentación de npm se explica cómo crear tokens de acceso de solo lectura personalizados. No recomendamos usar el archivo .npmrc creado en el directorio principal porque contiene un token de lectura y escritura. No se necesitan permisos de escritura durante la implementación, y podrían suponer un riesgo de seguridad.

No incluyas el archivo .npmrc si no usas repositorios privados, ya que puede aumentar el tiempo de implementación de tus funciones.

Nota: Si usas permisos personalizados (como los necesarios para VPC), asegúrate de permitir explícitamente que tus funciones accedan al repositorio privado de destino.

Formato de archivo

Si usas un archivo .npmrc para definir un token de autenticación personalizado, debe incluir la siguiente línea.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Sustituye:

• REGISTRY_DOMAIN: el nombre de dominio de tu registro privado de npm. Si tu repositorio está alojado en npmjs.org, asigna el valor registry.npmjs.org a este campo.

• AUTH_TOKEN: el token de autorización de tu registro npm. Puede ser el valor de texto literal del token o la cadena de texto ${NPM_TOKEN}, que npm sustituye por el valor del token real del entorno.

  Puedes definir la variable de entorno $NPM_TOKEN con el argumento --set-build-env-vars del comando gcloud functions deploy. Para obtener más información sobre el token de autenticación de NPM, consulta el tutorial de NPM sobre módulos privados.

Compilar la función con las dependencias copiadas

Las dependencias copiadas son aquellas cuya fuente se incluye directamente en el paquete de código fuente y se recompila junto con tu código. Puedes crear copias de las dependencias de Node.js y omitir su instalación durante la implementación mediante la variable de entorno de compilación GOOGLE_VENDOR_NPM_DEPENDENCIES.

Requisitos previos de las dependencias copiadas

1. Asegúrate de que tienes una función que funciona con todas las dependencias que quieras copiar en tu archivo package.json.

2. Instala estas dependencias de forma local ejecutando el siguiente comando:

       npm install
   

3. Quita node_modules del archivo .gcloudignore en tu directorio de trabajo.

4. Despliega la función y asegúrate de que tu versión local de Node.js sea la misma que la que especifiques durante el despliegue.

5. Despliega tu función y las dependencias copiadas con el siguiente comando:

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

   Sustituye:

   • SERVICE: el nombre de la función de Cloud Run que vas a desplegar
   • FUNCTION_ENTRY_POINT: con el punto de entrada a tu función en el código fuente.

Si especificas un motor npm en el archivo package.json, se descargará la versión especificada de npm durante la compilación. Para evitar este comportamiento, quítalo del archivo package.json.