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. Puedes usar npm, yarn, pnpm o Bun para instalar dependencias de Node.js.

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

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

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

Si el paquete de compilación de Node.js detecta un archivo de bloqueo, como package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock, o bun.lockb en tu proyecto, le da prioridad a ese archivo de bloqueo cuando instalas dependencias con npm ci, yarn install, pnpm install, o bun install.

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

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

Cloud Run importa la dependencia 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')}!`);
});

Usa npm para instalar módulos de Node.js localmente

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: Cloud Run Functions solo instala 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 Google Cloud productos. Consulta Bibliotecas cliente de Node.js.

Configura dependencias de implementación

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

Administrador de paquetes de NPM

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

npm install --production

Administrador de paquetes de Yarn

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

yarn install --production

Administrador de paquetes de Pnpm

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

pnpm install

Administrador de paquetes de Bun

El paquete de compilación de Node.js admite el administrador de paquetes de Bun. Con el administrador de paquetes de Bun, puedes instalar dependencias mientras mantienes la estructura del proyecto de Node.js y la versión del entorno de ejecución existentes. Puedes elegir cualquiera de los siguientes mecanismos para instalar dependencias con Bun:

• Detección automática: El paquete de compilación de Node.js detecta el administrador de paquetes de Bun cuando incluyes un archivo bun.lock o bun.lockb en tu proyecto. Para configurar la detección automática con Bun, sigue estos pasos:

  1. Crea el archivo de bloqueo:

     bun install --lockfile-only
     

  2. Para implementar en Cloud Run, ejecuta el siguiente comando:

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

• Participación explícita: Establece la variable de entorno GOOGLE_PACKAGE_MANAGER en bun. Con este método, no necesitas crear ni mantener archivos de bloqueo. Ejecuta el siguiente comando para implementar en Cloud Run:

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

Si bien el paquete de compilación usa Bun para instalar dependencias, el entorno de ejecución de Node.js aún ejecuta tu aplicación. Tu proyecto debe incluir un archivo package.json. Para obtener más detalles sobre los requisitos de configuración, consulta Cómo compilar una aplicación de Node.js en la documentación de Buildpacks.

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

Después de 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, Cloud Run Functions quita y vuelve a generar la carpeta node_modules instalando 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, Cloud Run Functions instala solo 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.

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 de forma manual como un archivo ZIP. Puedes implementar tu función de manera correcta 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 agregar a una lista 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 siguiente línea.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Reemplaza lo siguiente:

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

• AUTH_TOKEN: Es el token de autorización de tu registro de npm. Puede ser el valor de texto literal del token o la cadena de texto ${NPM_TOKEN}, que npm reemplaza con 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 detalles sobre el token de autenticación de NPM.

Crea tu función con dependencias copiadas

Las dependencias copiadas 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 copiadas 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 copiadas

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

2. Instala estas dependencias de manera local cuando ejecutes:

       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 copiadas con el siguiente comando:

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

   Reemplaza lo siguiente:

   • SERVICE: Es el nombre de la función de Cloud Run que estás implementando.
   • FUNCTION_ENTRY_POINT: Es el punto de entrada a tu función en tu código fuente.

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.