Spécifier les dépendances dans Node.js

Une fonction est autorisée à utiliser d'autres modules Node.js ainsi que des données locales. Dans Node.js, les dépendances sont gérées avec npm et exprimées dans un fichier de métadonnées appelé package.json. Vous pouvez utiliser npm, yarn, pnpm, ou Bun pour installer les dépendances Node.js.

Le Functions Framework Node.js est une dépendance requise pour toutes les fonctions. Bien que Cloud Run Functions l'installe en votre nom lors de la création de la fonction, nous vous recommandons de l'inclure en tant que dépendance explicite pour plus de clarté.

Si votre fonction repose sur des dépendances privées, nous vous recommandons de mettre en miroir functions-framework dans votre registre privé. Incluez la valeur mise en miroir functions-framework en tant que dépendance à votre fonction pour éviter d'installer le package depuis l'Internet public.

Pour spécifier une dépendance pour votre fonction, ajoutez-la au fichier package.json.

Si le buildpack Node.js détecte un fichier lock, tel que package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock, ou bun.lockb dans votre projet, il le priorise lorsque vous installez des dépendances à l'aide de npm ci, yarn install, pnpm install, ou bun install.

L'exemple suivant répertorie une dépendance dans le fichier package.json :

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

Cloud Run importe la dépendance dans la fonction :

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

Utiliser npm pour installer des modules Node.js localement

La méthode la plus simple pour installer un module Node.js localement consiste à utiliser la commande npm install dans le dossier contenant votre fonction Cloud Run. Par exemple, la commande suivante ajoute le module uuid :

npm install uuid

Cette commande a un double effet :

1. Elle définit la dernière version du module comme dépendance dans votre fichier package.json. C'est très important, car Cloud Run Functions n'installe que les modules qui sont déclarés dans votre fichier package.json.
2. Elle télécharge le module dans votre répertoire node_modules. Cela vous permet d'utiliser le module lors du développement local.

Si vous n'avez pas installé npm sur votre ordinateur, procurez-vous npm.

Remarque : Les packages npm sont disponibles pour divers Google Cloud produits. Consultez Bibliothèques clientes Node.js.

Configurer des dépendances de déploiement

Vous pouvez installer des dépendances en production pour NPM, Yarn ou Pnpm :

Gestionnaire de packages NPM

Lorsque vous déployez votre fonction, Cloud Run Functions installe les dépendances déclarées dans le fichier package.json à l'aide de la npm install commande :

npm install --production

Gestionnaire de packages Yarn

Dans l'environnement d'exécution Node.js 8 ou version ultérieure, si un fichier yarn.lock existe, les fonctions Cloud Run utilisent la yarn install commande :

yarn install --production

Gestionnaire de packages Pnpm

Dans l'environnement d'exécution Node.js 8 ou version ultérieure, si un pnpm-lock.yaml fichier existe, les fonctions Cloud Run utilisent la pnpm install commande :

pnpm install

Gestionnaire de packages Bun

Le buildpack Node.js est compatible avec le gestionnaire de packages Bun. Avec le gestionnaire de packages Bun, vous pouvez installer des dépendances tout en conservant la structure de votre projet Node.js et la version de l'environnement d'exécution existantes. Vous pouvez choisir l'un des mécanismes suivants pour installer des dépendances à l'aide de Bun :

• Détection automatique : le buildpack Node.js détecte le gestionnaire de packages Bun lorsque vous incluez un fichier bun.lock ou bun.lockb dans votre projet. Pour configurer la détection automatique avec Bun, procédez comme suit :

  1. Créez le fichier lock :

     bun install --lockfile-only
     

  2. Déployez-le sur Cloud Run en exécutant la commande suivante :

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

• Activation explicite : définissez la variable d'environnement GOOGLE_PACKAGE_MANAGER sur bun. Avec cette méthode, vous n'avez pas besoin de créer ni de gérer des fichiers lock. Exécutez la commande suivante pour effectuer le déploiement sur Cloud Run :

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

Bien que le buildpack utilise Bun pour installer les dépendances, l'environnement d'exécution Node.js exécute toujours votre application. Votre projet doit inclure un fichier package.json. Pour en savoir plus sur les exigences de configuration, consultez Créer une application Node.js dans la documentation Buildpacks.

Exécuter les étapes de compilation personnalisée lors du déploiement

Une fois le déploiement terminé, vous pouvez effectuer une étape de compilation personnalisée pendant le processus de compilation de la fonction en ajoutant un script gcp-build dans votre fichier package.json.

Lorsque ce script est exécuté, les dépendances des champs dependencies et devDependencies du fichier package.json sont disponibles. Après avoir exécuté l'étape de compilation personnalisée, Cloud Run Functions supprime et génère à nouveau le dossier node_modules en n'installant que les dépendances de l'environnement de production déclarées dans le champ dependencies du fichier package.json.

Si le fichier package.json ne contient pas de script gcp-build, les fonctions Cloud Run installent simplement les dépendances de l'environnement de production.

Utiliser des packages système

L'environnement d'exécution Node.js inclut également un certain nombre de packages système.

Inclure des modules Node.js locaux

Vous pouvez également inclure des modules Node.js locaux comme faisant partie de votre fonction. Pour ce faire, déclarez votre module dans le fichier package.json à l'aide du préfixe file:. Dans l'exemple suivant, mymodule fait référence au nom de votre module et mymoduledir correspond au répertoire contenant le module :

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

Le code de ce module local doit être stocké ailleurs que dans le dossier node_modules du répertoire racine de votre fonction.

Remarque : Si vous effectuez le déploiement au moyen de l'outil de ligne de commande gcloud, gcloud crée automatiquement un fichier .gcloudignore dans le répertoire de votre fonction. Par défaut, le dossier node_modules est ajouté à ce fichier .gcloudignore et n'est pas importé dans le cadre de votre déploiement. Vous n'avez pas besoin d'inclure le dossier node_modules lorsque vous importez manuellement le code sous forme de fichier ZIP. Vous pouvez déployer votre fonction sans le dossier node_modules.

Charger des modules Node.js

Utilisez la fonction require() Node.js pour charger les modules Node.js que vous avez installés. Vous pouvez également utiliser la fonction require() pour importer les fichiers locaux que vous déployez avec votre fonction.

Utiliser des modules privés

Vous pouvez utiliser un module npm privé en fournissant des paramètres d'authentification avec le registre dans un .npmrc fichier du répertoire de la fonction. Si vous utilisez comme gestionnaire de packages Yarn v2 ou une version ultérieure, ce fichier est nommé .yarnrc.yml.

Modules privés d'Artifact Registry

Un dépôt de packages Node.js Artifact Registry peut héberger des modules privés pour votre fonction. Lorsque vous déployez une fonction Cloud Run, le processus de compilation génère automatiquement des identifiants Artifact Registry pour le compte de service Cloud Build. Il vous suffit de répertorier le dépôt Artifact Registry dans votre fichier .npmrc sans générer d'identifiants supplémentaires. Exemple :

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

Cette approche fonctionne également pour le gestionnaire de packages Yarn v1. Si vous utilisez Yarn v2 ou une version ultérieure, il vous suffit de répertorier le dépôt Artifact Registry dans votre fichier .yarnrc.yml sans identifiants supplémentaires. Exemple :

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

Modules privés d'autres dépôts

La documentation npm explique comment créer des jetons d'accès personnalisés en lecture seule. Nous déconseillons l'utilisation du fichier .npmrc créé dans le répertoire d'accueil, car il contient un jeton de lecture/écriture. Les autorisations d'écriture ne sont pas requises pendant le déploiement et peuvent présenter un risque pour la sécurité.

N'incluez pas le fichier .npmrc si vous n'utilisez pas de dépôts privés, car cela peut augmenter le temps de déploiement de vos fonctions.

Remarque : Si vous utilisez des autorisations personnalisées (telles que celles nécessaires pour le VPC), assurez-vous qu'elles permettent explicitement à vos fonctions d'accéder au dépôt privé cible.

Format de fichier

Si vous utilisez un fichier .npmrc pour définir un jeton d'authentification personnalisé, il doit inclure la ligne ci-dessous.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Remplacez :

• REGISTRY_DOMAIN : le nom de domaine de votre registre npm privé. Si votre dépôt est hébergé avec npmjs.org, définissez ce champ sur registry.npmjs.org.

• AUTH_TOKEN : jeton d'autorisation de votre registre npm. Il peut s'agir de la valeur de texte littéral du jeton, ou de la chaîne de texte ${NPM_TOKEN}, que npm va remplacer par la valeur réelle du jeton, fournie par l'environnement.

  Vous pouvez définir la variable d'environnement $NPM_TOKEN avec l'argument --set-build-env-vars sur votre commande gcloud functions deploy. Pour en savoir plus sur le jeton d'authentification NPM, consultez le tutoriel NPM sur les modules privés.

Créer votre fonction avec des dépendances copiées

Les dépendances copiées sont celles dont la source est incluse directement dans votre package de code source et reconstruite avec votre propre code. Vous créez des dépendances Node.js copiées et vous ne les installez pas lors du déploiement à l'aide de la variable d'environnement de compilation GOOGLE_VENDOR_NPM_DEPENDENCIES.

Prérequis pour les dépendances copiées

1. Assurez-vous de disposer d'une fonction opérationnelle avec toutes les dépendances que vous souhaitez copier dans votre fichier package.json.

2. Installez ces dépendances localement en exécutant la commande suivante :

       npm install
   

3. Supprimez node_modules du fichier .gcloudignore dans votre répertoire de travail.

4. Déployez la fonction en vous assurant que votre version locale de Node.js est identique à celle que vous spécifiez lors du déploiement.

5. Déployez votre fonction et les dépendances copiées à l'aide de la commande suivante :

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

   Remplacez :

   • SERVICE : nom de la fonction Cloud Run que vous déployez
   • FUNCTION_ENTRY_POINT : point d'entrée de votre fonction dans votre code source.

Si vous spécifiez un moteur npm dans le fichier package.json, la version de npm spécifiée est téléchargée au moment de la compilation. Pour supprimer ce comportement, supprimez le moteur de votre fichier package.json.