Créer une application Node.js

Spécifier les versions de Node.js

Le projet des packs de création est compatible avec la version LTS actuelle et la version LTS active de Node.js. D'anciennes versions de Node.js sont disponibles, mais peuvent ne pas être gérées activement par le projet.

Utiliser package.json

Vous pouvez spécifier la version de Node.js de votre application lors du déploiement en configurant le champ engines.node dans package.json. Pour configurer le pack de création de manière à utiliser la dernière version de Node.js v16 lors du déploiement de votre application, vous pouvez utiliser les valeurs suivantes dans votre fichier package.json :

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

Utiliser GOOGLE_NODEJS_VERSION

Il est également possible de spécifier la version de Node.js via la variable d'environnement GOOGLE_NODEJS_VERSION. Si les deux configurations sont définies, la valeur GOOGLE_NODEJS_VERSION est prioritaire sur la propriété engines.node. Si aucune valeur n'est fournie, la version LTS la plus récente de Node.js est utilisée.

Pour configurer le buildpack afin d'utiliser Node.js 16 lors du déploiement de votre application, procédez comme suit :

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

Vous pouvez également utiliser un descripteur de projet project.toml pour encoder la variable d'environnement avec vos fichiers de projet. Consultez les instructions décrivant la compilation de l'application avec des variables d'environnement.

Conseils

  • Le champ engines.node peut accepter une contrainte semver. La bibliothèque spécifique que nous utilisons pour les buildpacks Node.js est Masterminds/semver.
  • Évitez d'utiliser les spécificateurs "plus de" (>) dans engines.node.
  • Lors du déploiement de l'application dans l'environnement standard App Engine, la propriété engines.node doit être compatible avec l'environnement d'exécution spécifié dans app.yaml.
  • Vous trouverez des informations supplémentaires sur l'option de configuration engines.node dans package.json en consultant la section sur les moteurs de la documentation officielle de NPM.
  • Lorsque vous déployez une fonction sur Cloud Functions, la propriété engines.node doit être compatible avec l'environnement d'exécution utilisé pour déployer votre fonction.

Installer les dépendances

Avec NPM

  • NPM est le gestionnaire de packages par défaut.
  • Dans la mesure du possible, utilisez package-lock.json pour améliorer les performances du cache.
  • Par défaut, seules les dépendances de production sont installées.
  • Vous pouvez spécifier la section de version npm à l'aide du champ engines.npm de votre fichier package.json.

Avec Yarn

  • Le fichier Yarn est utilisé lorsque vous incluez le fichier yarn.lock dans votre projet.
  • Vous pouvez spécifier la version de yarn à utiliser dans le champ engines.yarn de votre fichier package.json.
  • Nous prenons en charge le mode Yarn2 PnP si votre projet inclut un .yarn/cache.

Avec Pnpm

  • Pnpm est utilisé à la place lorsque vous incluez le fichier pnpm-lock.yaml dans votre projet.
  • Vous pouvez spécifier une version de pnpm dans le champ engines.pnpm de votre fichier package.json.
  • Pour obtenir un exemple fonctionnel, consultez l'application sample-node-pnpm.

Utiliser des modules privés

Vous pouvez utiliser un module npm privé en fournissant des paramètres d'authentification avec le registre dans un fichier .npmrc du répertoire de la fonction. Si vous utilisez Yarn version 2 ou une version ultérieure en tant que gestionnaire de packages, 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 Buildpacks, le processus de compilation génère automatiquement des identifiants Artifact Registry pour le compte de service Cloud Build. Vous ne devez répertorier le dépôt Artifact Registry dans votre fichier .npmrc que si vous utilisez NPM ou Yarn version 1. Par exemple, lorsque vous utilisez NPM ou Yarn version 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 vous utilisez Yarn version 2 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. Par 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.

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é. Par exemple, si l'hôte de votre dépôt est 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 la commande npm remplace 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.

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

Par défaut, npm run build est exécuté si un script est spécifié dans votre fichier package.json. Toutefois, vous pouvez plutôt spécifier des étapes de compilation personnalisées pour remplacer le comportement par défaut et n'exécuter que les scripts souhaités lors de la compilation. Vous pouvez contrôler les étapes de compilation à l'aide de la variable d'environnement GOOGLE_NODE_RUN_SCRIPTS ou de gcp-build dans votre fichier package.json.

Vous ne pouvez utiliser qu'une seule méthode. Notez que la variable d'environnement GOOGLE_NODE_RUN_SCRIPTS est prioritaire et remplace tout ce qui est spécifié pour gcp-build dans votre package.json.

Par défaut, lorsque vous configurez des étapes de compilation personnalisées, les dependencies et devDependencies de votre fichier package.json sont installés en premier avant l'exécution des scripts ou des commandes. Pour remplacer le comportement par défaut, vous pouvez utiliser la variable d'environnement NODE_ENV.

Utiliser GOOGLE_NODE_RUN_SCRIPTS

Vous pouvez transmettre la variable d'environnement GOOGLE_NODE_RUN_SCRIPTS à la compilation pour contrôler les scripts à exécuter. Vous pouvez spécifier un ou plusieurs scripts ou transmettre à la place une variable d'environnement vide pour empêcher le comportement par défaut, tel que GOOGLE_NODE_RUN_SCRIPTS=. Pour plus d'informations, consultez la section Variables d'environnement.

Utiliser package.json

L'ajout de gcp-build dans votre fichier package.json n'exécute que npm run gcp-build, ce qui signifie qu'il remplace le comportement par défaut. Vous pouvez spécifier une ou plusieurs commandes, ou spécifier à la place une chaîne vide pour empêcher l'exécution d'une commande, par exemple "gcp-build":"".

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

Point d'entrée de l'application

Le buildpack Node.js exécute la commande spécifiée dans le champ scripts.start de votre package.json. Si scripts.start n'est pas défini, le buildpack exécutera npm start.

Nous vous recommandons d'utiliser un fichier Procfile, car il exclut npm ou yarn.

Environment variables

Vous pouvez définir des variables d'environnement pour configurer des compilations de votre image de conteneur.

Le buildpack Node.js est compatible avec les variables d'environnement suivantes pour personnaliser votre conteneur.

NPM_CONFIG_<key>

Consultez la documentation.

Exemple : NPM_CONFIG_FLAG=value transmet -flag=value aux commandes npm.

NODE_ENV

Spécifie l'environnement de développement pendant la compilation ; défini pour npm install

Exemple : NODE_ENV=development installe à la fois les dependencies et devDependencies spécifiés dans package.json.

GOOGLE_NODE_RUN_SCRIPTS

Spécifie une liste numérotée de scripts npm provenant de package.json à exécuter après l'installation de dépendances. Cette liste doit être séparée par une virgule et s'exécute dans l'ordre dans lequel vous répertoriez chaque script.

Lorsque vous spécifiez GOOGLE_NODE_RUN_SCRIPTS, seuls les scripts que vous répertoriez sont exécutés. Par exemple, si vous souhaitez empêcher l'exécution de la valeur npm run build par défaut, vous pouvez spécifier la variable d'environnement sans valeur.

Exemples :

  • GOOGLE_NODE_RUN_SCRIPTS=lint,build exécute npm run lint, puis npm run build.
  • GOOGLE_NODE_RUN_SCRIPTS= n'exécute aucun script.