Compila una aplicación de Node.js

Especifica versiones de Node.js

El proyecto de paquetes de compilación proporciona compatibilidad con las versiones LTS actuales y activas de Node.js. Las versiones anteriores de Node.js están disponibles, pero es posible que el proyecto no las mantenga activamente.

Usa package.json

Puedes especificar la versión de Node.js de tu aplicación durante la implementación si configuras el campo engines.node en package.json. A fin de configurar el paquete de compilación para que use la versión más reciente de Node.js v16 cuando implementes tu app, puedes usar los siguientes valores en tu package.json:

"engines": {
  "node": "16.x.x"
}

Usa GOOGLE_NODEJS_VERSION

También es posible especificar la versión de Node.js a través de la variable de entorno GOOGLE_NODEJS_VERSION. Si ambas configuraciones se establecen, el valor GOOGLE_NODEJS_VERSION tiene prioridad sobre la propiedad engines.node. Si no se proporciona ningún valor, se usa la versión más reciente de LTS de Node.js.

A fin de configurar el paquete de compilación para que use Node.js 16 cuando implementes tu app, haz lo siguiente:

pack build --builder=gcr.io/buildpacks/builder \
   sample-functions-framework-node \
   --env GOOGLE_NODEJS_VERSION=16.x.x

También puedes usar un descriptor de proyectos project.toml para codificar la variable de entorno junto con los archivos de tu proyecto. Consulta las instrucciones para compilar la aplicación con variables de entorno.

Sugerencias

  • El campo engines.node puede tomar una restricción semver. La biblioteca específica que usamos para los paquetes de compilación de Node.js es Masterminds/semver
  • Evita usar especificadores mayores que (>) en engines.node
  • Cuando implementas la aplicación en el entorno estándar de App Engine, la propiedad engines.node debe ser compatible con el entorno de ejecución especificado en app.yaml.
  • Puedes encontrar documentación adicional sobre la opción de configuración engines.node en package.json en la documentación oficial de NPM en el tema motores
  • Cuando implementas una función en Cloud Functions, la propiedad engines.node debe ser compatible con el entorno de ejecución que se usa para implementar la función.

Instala dependencias

Utiliza NPM

  • NPM es el administrador de paquetes predeterminado.
  • Siempre que sea posible, usa package-lock.json para mejorar el rendimiento de la caché.
  • De forma predeterminada, solo se instalan las dependencias de producción.
  • Puedes especificar la sección de la versión de la Administración de socios de red mediante el campo engines.npm en el archivo package.json.

Utiliza Yarn

  • En su lugar, se usa Yarn cuando incluyes el archivo yarn.lock en tu proyecto.
  • Puedes especificar la versión de yarn para usar en el campo engines.yarn del archivo package.json.
  • Admitimos el modo PrnP de Yarn2 si tu proyecto incluye una .yarn/cache.

Usa Pnpm

  • Pnpm se usa en su lugar cuando incluyes el archivo pnpm-lock.yaml en el proyecto.
  • Puedes especificar una versión de pnpm en el campo engines.pnpm del archivo package.json.
  • Para ver un ejemplo funcional, consulta la app de sample-node-pnpm.

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 la versión 2 de Yarn o una posterior, 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 Buildpacks, 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 cuando uses NPM o Yarn versión 1. Por ejemplo, cuando usas NPM o Yarn versión 1:

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

Si usas Yarn versión 2 o una versión posterior, solo debes enumerar el repositorio de Artifact Registry en tu archivo .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.

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 la Administración de socios de red. Por ejemplo, si el host de tu repositorio es npmjs.org, configura este campo como registry.npmjs.org.

  • AUTH_TOKEN: es el token de autorización para tu registro de la Administración de socios de red. Puede ser el valor de texto literal del token o la cadena de texto ${NPM_TOKEN}, que el comando 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.

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

De forma predeterminada, se ejecuta npm run build si se especifica una secuencia de comandos en el archivo package.json. Sin embargo, puedes especificar pasos de compilación personalizados para anular el comportamiento predeterminado y ejecutar solo las secuencias de comandos que deseas durante la compilación. Puedes controlar los pasos de compilación mediante la variable de entorno GOOGLE_NODE_RUN_SCRIPTS o el gcp-build en el archivo package.json.

Solo puedes usar un método. Ten en cuenta que la variable de entorno GOOGLE_NODE_RUN_SCRIPTS tiene prioridad y anula todo lo que se especifique para gcp-build en tu package.json.

De forma predeterminada, cuando configuras los pasos de compilación personalizados, las dependencies y devDependencies en tu archivo package.json se instalan primero antes de que se ejecuten cualquier secuencia de comandos o comandos. Para anular el comportamiento predeterminado, puedes usar la variable de entorno NODE_ENV.

Usa GOOGLE_NODE_RUN_SCRIPTS

Puedes pasar la variable de entorno GOOGLE_NODE_RUN_SCRIPTS a la compilación para controlar qué secuencias de comandos se ejecutan. Puedes especificar una o más secuencias de comandos o, en su lugar, pasar una variable de entorno vacía para evitar que se ejecute el comportamiento predeterminado, como GOOGLE_NODE_RUN_SCRIPTS=. Para obtener detalles completos, consulta Variables de entorno.

Usa package.json

Agregar gcp-build en tu archivo package.json solo ejecuta npm run gcp-build, lo que significa que anula el comportamiento predeterminado. Puedes especificar uno o más comandos, o una string vacía para evitar que se ejecute cualquier comando, como "gcp-build":"".

"scripts": {
  ...
  "gcp-build": "npm run lint && npm run build"
  ...
}

Punto de entrada de la aplicación

El paquete de compilación de Node.js ejecutará el comando especificado en el campo scripts.start de tu package.json. Si scripts.start no se configura, el paquete de compilación ejecutará npm start.

Recomendamos usar un Procfile, ya que quita npm o yarn de la ruta.

Variables de entorno

Puedes establecer variables de entorno para configurar compilaciones de la imagen de contenedor.

El paquete de compilación de Node.js admite las siguientes variables de entorno para personalizar tu contenedor.

NPM_CONFIG_<key>

Ver la documentación.

Ejemplo: NPM_CONFIG_FLAG=value pasa los comandos -flag=value a npm.

NODE_ENV

Especifica el entorno de desarrollo durante la compilación; configurado para npm install.

Ejemplo: NODE_ENV=development instala dependencies y devDependencies especificados en package.json.

GOOGLE_NODE_RUN_SCRIPTS

Especifica una lista ordenada de secuencias de comandos de la Administración de socios de red de package.json para que se ejecuten después de instalar dependencias. La lista debe estar separada por comas y se ejecuta en el orden en que enumeras cada secuencia de comandos.

Cuando especificas GOOGLE_NODE_RUN_SCRIPTS, solo se ejecutan las secuencias de comandos que enumeras. Por ejemplo, si deseas evitar que se ejecute el npm run build predeterminado, debes especificar la variable de entorno sin un valor.

Ejemplos:

  • GOOGLE_NODE_RUN_SCRIPTS=lint,build ejecuta npm run lint y, luego, npm run build.
  • GOOGLE_NODE_RUN_SCRIPTS= no ejecuta secuencias de comandos.