Especifica dependencias en Node.js

Las funciones pueden usar módulos de Node.js externos y datos locales. Las dependencias en Node.js se administran con npm y se expresan en un archivo de metadatos llamado package.json. Los tiempos de ejecución de Node.js para funciones de Cloud Run admiten la instalación con npm, yarn o pnpm.

Si quieres especificar una dependencia para tu función, agrégala al archivo package.json.

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

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

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

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

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

Si tu función depende de dependencias privadas, te recomendamos que dupliques functions-framework en tu registro privado. Incluye el functions-framework duplicado como una dependencia en tu función para evitar la instalación del paquete desde la Internet pública.

Instala módulos de Node.js localmente con npm

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

npm install uuid

Esto combina dos pasos:

1. Marca la última versión del módulo como una dependencia en tu archivo package.json. Esto es muy importante: Las funciones de Cloud Run solo instalan módulos que están declarados en tu archivo package.json.
2. Descarga el módulo en tu directorio node_modules. Esto te permite usar el módulo cuando desarrollas de forma local.

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

Nota: Los paquetes de npm están disponibles para una variedad de productos de Google Cloud. Consulta la lista aquí.

Configura dependencias de implementación

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

NPM

Cuando implementas tu función, las funciones de Cloud Run instalan las dependencias declaradas en el archivo package.json con el comando npm install:

npm install --production

Yarn

En el entorno de ejecución de Node.js 8 y versiones posteriores, si existe un archivo yarn.lock, las funciones de Cloud Run usan el comando yarn install en su lugar:

yarn install --production

Pnpm

En el entorno de ejecución de Node.js 8 y versiones posteriores, si existe un archivo pnpm-lock.yaml, las funciones de Cloud Run usan el comando pnpm install en su lugar:

pnpm install

Nota: Las dependencias declaradas en los subdirectorios no están instaladas. Si usas un repositorio monolítico, te recomendamos ejecutar una secuencia de comandos de compilación personalizada durante la implementación para instalar esas dependencias.

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

Después de realizar la implementación, puedes realizar una etapa de compilación personalizada durante el proceso de compilación de la función agregando una secuencia de comandos gcp-build en el archivo package.json.

Cuando se ejecuta esta secuencia de comandos, las dependencias en los campos dependencies y devDependencies del archivo package.json están disponibles. Después de ejecutar este paso, las funciones de Cloud Run quitan 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 una secuencia de comandos gcp-build en package.json, las funciones de Cloud Run solo instalan dependencias de producción.

Usa paquetes del sistema

El entorno de ejecución de Node.js también incluye una cantidad de paquetes del sistema. Si la función usa una dependencia que requiere un paquete que no aparece en la lista, puedes solicitar un paquete.

Nota: También puedes implementar versiones en contenedores de tus funciones de Cloud Run para Node.js en Cloud Run mediante Functions Framework.

Incluye 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 el módulo en package.json mediante el prefijo file:. En el siguiente ejemplo, 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 dentro del directorio raíz de la función.

Nota: Si realizas la implementación mediante la herramienta de línea de comandos de gcloud, gcloud crea de forma automática un archivo .gcloudignore en el directorio la función. De forma predeterminada, la carpeta node_modules se agrega a este .gcloudignore y no se sube como parte de la implementación. No es necesario que incluyas la carpeta node_modules cuando subes el código manualmente como un archivo ZIP .Puedes implementar correctamente tu función sin la carpeta node_modules.

Carga módulos Node.js

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

Usa módulos privados

Para usar un módulo de npm privado, proporciona la configuración para autenticarte con el registro en un archivo .npmrc en el directorio de la función. Si usas Yarn v2 o una versión superior como administrador de paquetes, este archivo se llamará .yarnrc.yml.

Módulos privados de Artifact Registry

Un repositorio de paquetes de Node.js en Artifact Registry puede alojar módulos privados para tu función. Cuando implementas una función de Cloud Run, el proceso de compilación genera de forma automática las credenciales de Artifact Registry para la cuenta de servicio de Cloud Build. Solo necesitas enumerar el repositorio de Artifact Registry en tu archivo .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 para el administrador de paquetes de Yarn v1. Si usas Yarn v2 o una versión posterior, solo debes agregar a una lista 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 tus propios tokens de acceso de solo lectura. No recomendamos el uso del archivo .npmrc que se creó en el directorio principal porque contiene un token de lectura/escritura. No se necesitan permisos de escritura para el proceso de implementación. Además, podrían poner en riesgo la 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 de forma explícita 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, el archivo debe incluir la línea que se muestra a continuación.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Reemplaza lo siguiente:

• REGISTRY_DOMAIN es el nombre de dominio de tu registro privado de npm. Si tu repositorio está alojado en npmjs.org, establece este campo en registry.npmjs.org.

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

  Puedes establecer la variable de entorno $NPM_TOKEN con el argumento --set-build-env-vars en el comando gcloud functions deploy. Consulta el instructivo de NPM sobre los módulos privados para obtener más información sobre el token de autenticación de NPM.

Crea tu función con dependencias de proveedores

Las dependencias de vendoring son aquellas cuyos orígenes se incluyen directamente en tu paquete de código fuente y que vuelven a compilarse junto con tu propio código. Crea dependencias de vendoring de Node.js y evita tener que instalarlas durante su implementación mediante la variable de entorno de compilación GOOGLE_VENDOR_NPM_DEPENDENCIES.

Requisitos previos para dependencias de proveedores

1. Asegúrate de tener una función de trabajo con todas las dependencias que deseas definir del proveedor en tu archivo package.json.

2. Instala estas dependencias de manera local al ejecutar:

       npm install
   

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

4. Implementa la función para asegurarte de que tu versión local de Node.js sea la misma que especificaste durante la implementación.

5. Implementa tu función y las dependencias del proveedor con el siguiente comando:

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

   Reemplaza lo siguiente:

   • FUNCTION_NAME: el nombre de la función de Cloud Run que estás implementando
   • RUNTIME_NAME: El nombre del entorno de ejecución de Node.js en el que ejecutarás la función implementada. Debe ser la misma versión de Node.js que usaste en tu entorno de desarrollo local

El paquete de Functions Framework es una dependencia obligatoria para las funciones. Para compilaciones más rápidas, recomendamos usar este paquete. Si no lo haces, se descarga e instala cuando se compila la función.

Si especificas un motor de npm en el archivo package.json, se descarga la versión especificada de npm en el tiempo de compilación. Para suprimir este comportamiento, quítalo de tu archivo con package.json.