Gestione delle dipendenze


Una funzione può utilizzare moduli Node.js esterni e dati locali. Le dipendenze in Node.js vengono gestite con npm ed espresse in un file di metadati denominato package.json. I runtime Node.js di Cloud Functions supportano l'installazione tramite npm, yarn o pnpm.

Per specificare una dipendenza per la tua funzione, aggiungila al file package.json.

In questo esempio, una dipendenza è elencata nel file package.json:

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

La dipendenza viene quindi importata nella funzione:

JavaScript

const onRequest = require("firebase-functions/https");
const escapeHtml = require("escape-html");

// Return a greeting with the input HTML-escaped.
exports.hello = onRequest((req, res) => {
  res.send(Hello ${escapeHtml(req.query.name || req.body.name || "World")}!`);
});

TypeScript

import { onRequest } from "firebase-functions/https";
import * as escapeHtml from "escape-html";

// Return a greeting with the input HTML-escaped.
export let hello = onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || "World")}!`);

Inclusione di moduli Node.js locali

Puoi anche includere moduli Node.js locali come parte della funzione. Puoi ottenere questo risultato dichiarando il modulo in package.json utilizzando il prefisso file:. Nell'esempio seguente, mymodule si riferisce al nome del modulo e mymoduledir è la directory contenente il modulo:

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

Il codice di questo modulo locale deve essere archiviato in una posizione diversa dalla cartella node_modules all'interno della directory root della funzione.

Passaggi aggiuntivi per TypeScript

TypeScript è più utile quando utilizzi librerie con informazioni sui tipi. In questo modo, TypeScript rileva gli errori di sintassi e gli editor forniscono suggerimenti di completamento automatico migliori. Alcune librerie, come firebase-admin e firebase-functions, vengono fornite con le definizioni TypeScript incluse.

Molte librerie non forniscono una propria definizione TypeScript. Il progetto DefinitelyTyped fornisce definizioni gestite dalla community per le librerie di nodi più popolari. DefinitelyTyped pubblica queste definizioni con lo stesso nome del pacchetto NPM, ma all'interno dell'organizzazione "@types". Ad esempio, puoi installare le informazioni sul tipo per la libreria uuid con il seguente comando:

npm install @types/uuid

Man mano che acquisisci familiarità con TypeScript, potresti ritrovarti a combinare entrambe le installazioni:

npm install uuid @types/uuid

Le dipendenze di tipo devono essere dello stesso tipo della dipendenza della libreria. Ad esempio, non devi salvare uuid come dipendenza normale e @types/uuid come dipendenza di sviluppo o peer.

Caricamento dei moduli Node.js

Utilizza la funzione Node.js require() per caricare qualsiasi modulo Node.js installato. Puoi anche utilizzare la funzione require() per importare i file locali di cui esegui il deployment insieme alla funzione.

Se scrivi funzioni in TypeScript, utilizza l'istruzione import nello stesso modo per caricare qualsiasi modulo Node.js installato.

Utilizzo di moduli privati

Puoi utilizzare un modulo npm privato fornendo le impostazioni per l'autenticazione con il registro in un file .npmrc nella directory della funzione. Se utilizzi Yarn v2 o versioni successive come gestore di pacchetti, questo file è denominato .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 Google Cloud Functions, il processo di compilazione genera automaticamente le credenziali Artifact Registry per il service account Cloud Build. Devi solo elencare il repository Artifact Registry in .npmrc senza generare credenziali aggiuntive. Ad esempio:

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

Questo approccio funziona anche per il gestore di pacchetti Yarn v1. Se utilizzi Yarn v2 o versioni successive, devi solo elencare il repository Artifact Registry in .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 di sola lettura personalizzati. Sconsigliamo l'utilizzo del file .npmrc creato nella directory home perché contiene un token di lettura/scrittura. Le autorizzazioni in scrittura non sono richieste durante il deployment e potrebbero rappresentare un rischio per la sicurezza.

Non includere il file .npmrc se non utilizzi repository privati, in quanto può aumentare il tempo di deployment delle tue funzioni.

Formato file

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

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Sostituisci:

  • REGISTRY_DOMAIN: il nome di dominio del tuo registro npm privato. Se il tuo repository è ospitato su npmjs.org, imposta questo campo su registry.npmjs.org.

  • AUTH_TOKEN: il token di autorizzazione per il tuo registro npm. Può trattarsi del valore di testo letterale del token o della stringa di testo ${NPM_TOKEN}, che npm sostituisce con il valore effettivo del token dell'ambiente.

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