Creazione di un'applicazione Node.js

Specifica delle versioni di Node.js

Il progetto buildpack fornisce il supporto per le release LTS correnti e attive di Node.js. Sono disponibili release precedenti di Node.js, ma potrebbero non essere attivamente mantenute dal progetto.

Uso: package.json

Puoi specificare la versione Node.js della tua applicazione durante il deployment configurando il campo engines.node in package.json. Per configurare il buildpack in modo che utilizzi la versione più recente di Node.js 16 durante il deployment dell'app, puoi utilizzare i seguenti valori in package.json:

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

Uso: GOOGLE_NODEJS_VERSION

È anche possibile specificare la versione di Node.js tramite la variabile di ambiente GOOGLE_NODEJS_VERSION. Se sono impostate entrambe le configurazioni, il valore GOOGLE_NODEJS_VERSION ha la precedenza sulla proprietà engines.node. Se non viene fornito alcun valore, viene utilizzata la versione LTS più recente di Node.js

Per configurare il buildpack in modo che utilizzi Node.js 16 durante il deployment dell'app:

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

Puoi anche utilizzare un descrittore del progetto project.toml per codificare la variabile di ambiente insieme ai file del progetto. Consulta le istruzioni sulla creazione dell'applicazione con le variabili di ambiente.

Suggerimenti

  • Il campo engines.node può accettare un vincolo semver. La libreria specifica che utilizziamo per i buildpack Node.js è Masterminds/semver
  • Evita di utilizzare specificatori maggiore di (>) in engines.node
  • Quando esegui il deployment dell'applicazione nell'ambiente standard di App Engine, la proprietà engines.node deve essere compatibile con il runtime specificato in app.yaml
  • Ulteriori informazioni sull'opzione di configurazione engines.node in package.json sono disponibili nella documentazione ufficiale di NPM nell'argomento engine
  • Quando esegui il deployment di una funzione in Cloud Run Functions, la proprietà engines.node deve essere compatibile con il runtime utilizzato per il deployment della funzione

Installazione delle dipendenze

Utilizzo di NPM

  • NPM è il gestore dei pacchetti predefinito.
  • Ove possibile, utilizza package-lock.json per migliorare il rendimento della cache.
  • Per impostazione predefinita vengono installate solo le dipendenze di produzione.
  • Puoi specificare la sezione della versione npm utilizzando il campo engines.npm nel package.json file.

Utilizzo di Yarn

  • Quando includi il file yarn.lock nel progetto, viene utilizzato Yarn.
  • Puoi specificare la versione del filato da utilizzare nel campo engines.yarn del package.json file.
  • Supportiamo la modalità PnP di Yarn2 se il tuo progetto include un .yarn/cache.

Utilizzo di Pnpm

  • Pnpm viene utilizzato invece quando includi il file pnpm-lock.yaml nel progetto.
  • Puoi specificare una versione di pnpm nel campo engines.pnpm del file package.json.
  • Per un esempio funzionante, consulta l'app sample-node-pnpm.

Utilizzo di moduli privati

Puoi utilizzare un modulo npm privato fornendo le impostazioni per l'autenticazione con il registry in un file .npmrc nella directory della funzione. Se utilizzi Yarn 2 o versioni successive come gestore dei pacchetti, questo file si chiama .yarnrc.yml.

Moduli privati di Artifact Registry

Un repository di pacchetti Node.js di Artifact Registry può ospitare moduli privati per la tua funzione. Quando esegui il deployment di una funzione Buildpack, il processo di compilazione genera automaticamente le credenziali di Artifact Registry per l'account di servizio Cloud Build. Devi elencare il repository Artifact Registry nel file .npmrc solo se utilizzi NPM o Yarn versione 1. Ad esempio, quando utilizzi NPM o Yarn versione 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

Se utilizzi Yarn 2 o versioni successive, devi solo elencare il repository Artifact Registry nel file .yarnrc.yml senza credenziali aggiuntive. Ad esempio:

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

Moduli privati di altri repository

La documentazione di npm spiega come creare token di accesso personalizzati di sola lettura. Sconsigliamo di utilizzare il file .npmrc creato nella directory home perché contiene un token di lettura/scrittura. Le autorizzazioni di scrittura non sono obbligatorie durante il deployment e potrebbero rappresentare un rischio per la sicurezza.

Non includere il file .npmrc se non utilizzi repository privati, poiché questo può aumentare il tempo di implementazione delle funzioni.

Formato file

Se utilizzi un file .npmrc per impostare un token di autenticazione personalizzato, deve includere la riga riportata di seguito.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Sostituisci:

  • REGISTRY_DOMAIN: il nome di dominio del tuo registry npm privato. Ad esempio, se l'host del repository è npmjs.org, imposta questo campo su registry.npmjs.org.

  • AUTH_TOKEN: il token di autorizzazione per il tuo registry npm. Può essere il valore di testo letterale del token o la stringa di testo ${NPM_TOKEN}, che il comando npm sostituisce con il valore effettivo del token dall'ambiente.

    Puoi impostare la variabile di ambiente $NPM_TOKEN con l'argomento --set-build-env-vars per il comando gcloud functions deploy. Per ulteriori dettagli sul token di autenticazione NPM, consulta il tutorial di NPM sui moduli privati.

Esecuzione di passaggi di build personalizzati durante il deployment

Per impostazione predefinita, npm run build viene eseguito se nel file package.json è specificato uno script. Tuttavia, puoi specificare passaggi di compilazione personalizzati per eseguire il override del comportamento predefinito ed eseguire solo gli script che ti interessano durante la compilazione. Puoi controllare i passaggi di compilazione utilizzando la variabile di ambiente GOOGLE_NODE_RUN_SCRIPTS o gcp-build nel file package.json.

Puoi utilizzare un solo metodo. Tieni presente che la variabile di ambiente GOOGLE_NODE_RUN_SCRIPTS ha la precedenza e sostituisce tutto ciò che è specificato per gcp-build in package.json.

Per impostazione predefinita, quando configuri i passaggi di compilazione personalizzati, vengono installati prima sia dependencies sia devDependencies nel file package.json prima che vengano eseguiti script o comandi. Per eseguire l'override del comportamento predefinito, puoi utilizzare la variabile di ambiente NODE_ENV.

Uso: GOOGLE_NODE_RUN_SCRIPTS

Puoi passare la variabile di ambiente GOOGLE_NODE_RUN_SCRIPTS alla compilazione per controllare gli script da eseguire. Puoi specificare uno o più script oppure passare una variabile di ambiente vuota per impedire l'esecuzione del comportamento predefinito, ad esempio GOOGLE_NODE_RUN_SCRIPTS=. Per maggiori dettagli, consulta Voci di ambiente.

Uso: package.json

L'aggiunta di gcp-build nel file package.json esegue solo npm run gcp-build, il che significa che sostituisce il comportamento predefinito. Puoi specificare uno o più comandi oppure una stringa vuota per impedire l'esecuzione di qualsiasi comando, ad esempio "gcp-build":"".

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

Punto di ingresso dell'applicazione

Il buildpack Node.js eseguirà il comando specificato nel campo scripts.start di package.json. Se scripts.start non è impostato, il buildpack eseguirà npm start.

Ti consigliamo di utilizzare un file Procfile perché rimuove npm o yarn dal percorso.

Variabili di ambiente

Puoi impostare variabili di ambiente per configurare le build dell'immagine container.

Il buildpack Node.js supporta le seguenti variabili di ambiente per personalizzare il contenitore.

NPM_CONFIG_<key>

Consulta la documentazione.

Esempio: NPM_CONFIG_FLAG=value passa -flag=value ai comandi npm.

NODE_ENV

Specifica l'ambiente di sviluppo durante la compilazione. Impostato su npm install.

Esempio: NODE_ENV=development installa sia dependencies che devDependencies specificati in package.json.

GOOGLE_NODE_RUN_SCRIPTS

Specifica un elenco ordinato di script npm da package.json da eseguire dopo l'installazione delle dipendenze. L'elenco deve essere separato da virgole ed eseguito nell'ordine in cui elenchi ogni script.

Se specifichi GOOGLE_NODE_RUN_SCRIPTS, vengono eseguiti solo gli script elencati. Ad esempio, se vuoi impedire l'esecuzione di npm run build predefinito, specifica la variabile di ambiente senza un valore.

Esempi:

  • GOOGLE_NODE_RUN_SCRIPTS=lint,build esegue npm run lint e poi npm run build.
  • GOOGLE_NODE_RUN_SCRIPTS= non esegue script.