Firebase in dynamischen Webanwendungen mit SSR (serverseitiges Rendering) verwenden

Wenn Sie mit dem Firebase JS SDK oder anderen Firebase-Client-SDKs gearbeitet haben, sind Sie wahrscheinlich mit der FirebaseApp-Schnittstelle und ihrer Verwendung zum Konfigurieren von App-Instanzen vertraut. Um ähnliche Vorgänge auf der Serverseite zu ermöglichen, stellt Firebase FirebaseServerApp bereit.

FirebaseServerApp ist eine Variante von FirebaseApp für die Verwendung in serverseitigen Rendering-Umgebungen (SSR). Es enthält Tools, mit denen Firebase-Sitzungen fortgesetzt werden können, die die Grenze zwischen clientseitigem Rendering (CSR) und serverseitigem Rendering (SSR) überschreiten. Mit diesen Tools und Strategien können Sie dynamische Webanwendungen verbessern, die mit Firebase erstellt und in Google-Umgebungen wie Firebase App Hosting bereitgestellt werden.

Funktionen von FirebaseServerApp:

  • Führen Sie serverseitigen Code im Nutzerkontext aus, im Gegensatz zum Firebase Admin SDK, das über vollständige Administratorrechte verfügt.
  • Aktivieren Sie die Verwendung von App Check in SSR-Umgebungen.
  • Firebase Auth-Sitzung fortsetzen, die im Client erstellt wurde.

Der FirebaseServerApp-Lebenszyklus

Frameworks für serverseitiges Rendering (SSR) und andere Nicht-Browser-Laufzeiten wie Cloud-Worker optimieren die Initialisierungszeit, indem sie Ressourcen über mehrere Ausführungen hinweg wiederverwenden. FirebaseServerApp ist so konzipiert, dass diese Umgebungen mithilfe eines Referenzzählmechanismus berücksichtigt werden. Wenn eine App initializeServerApp mit denselben Parametern wie eine vorherige initializeServerApp aufruft, erhält sie dieselbe FirebaseServerApp-Instanz, die bereits initialisiert wurde. Dadurch werden unnötiger Initialisierungsaufwand und unnötige Arbeitsspeicherzuweisungen reduziert. Wenn deleteApp für eine FirebaseServerApp-Instanz aufgerufen wird, wird die Referenzanzahl reduziert. Die Instanz wird freigegeben, wenn die Referenzanzahl null erreicht.

FirebaseServerApp-Instanzen werden bereinigt

Es kann schwierig sein, zu wissen, wann deleteApp für eine FirebaseServerApp-Instanz aufgerufen werden muss, insbesondere wenn Sie viele asynchrone Vorgänge parallel ausführen. Das Feld releaseOnDeref von FirebaseServerAppSettings vereinfacht dies. Wenn Sie releaseOnDeref einen Verweis auf ein Objekt mit der Lebensdauer des Anfragebereichs zuweisen (z. B. das Header-Objekt der SSR-Anfrage), reduziert FirebaseServerApp die Anzahl der Verweise, wenn das Framework das Header-Objekt zurückfordert. Dadurch wird Ihre FirebaseServerApp-Instanz automatisch bereinigt.

Hier ein Beispiel für die Verwendung von releaseOnDeref:

/// Next.js
import { headers } from 'next/headers'
import { FirebaseServerAppSettings, initializeServerApp} from "firebase/app";

export default async function Page() {
  const headersObj = await headers();
  let appSettings: FirebaseServerAppSettings = {};
  appSettings.releaseOnDeref = headersObj;
  const serverApp = initializeServerApp(firebaseConfig, appSettings);
  ...
}

Auf dem Client erstellte authentifizierte Sitzungen fortsetzen

Wenn eine Instanz von FirebaseServerApp mit einem Auth-ID-Token initialisiert wird, ermöglicht sie die Überbrückung authentifizierter Nutzersitzungen zwischen den Umgebungen für clientseitiges Rendering (CSR) und serverseitiges Rendering (SSR). Instanzen des Firebase Auth SDK, die mit einem FirebaseServerApp-Objekt initialisiert wurden, das ein Auth-ID-Token enthält, versuchen, den Nutzer bei der Initialisierung anzumelden, ohne dass die Anwendung Anmeldemethoden aufrufen muss.

Durch die Bereitstellung eines Auth-ID-Tokens können Apps jede der Anmeldemethoden von Auth auf dem Client verwenden. So wird sichergestellt, dass die Sitzung auf der Serverseite fortgesetzt wird, auch bei Anmeldemethoden, die eine Nutzerinteraktion erfordern. Außerdem können rechenintensive Vorgänge wie authentifizierte Firestore-Abfragen auf den Server ausgelagert werden, was die Rendering-Leistung Ihrer App verbessern sollte.

/// Next.js
import { initializeServerApp } from "firebase/app";
import { getAuth } from "firebase/auth";

// Replace the following with your app's
// Firebase project configuration
const firebaseConfig = {
  // ...
};

const firebaseServerAppSettings = {
  authIdToken: token  // See "Pass client tokens to the server side
                      // rendering phase" for an example on how transmit
                      // the token from the client and the server.
}

const serverApp =
  initializeServerApp(firebaseConfig,
                      firebaseServerAppSettings);
const serverAuth = getAuth(serverApp);

// FirebaseServerApp and Auth will now attempt
// to sign in the current user based on provided
// authIdToken.

App Check in SSR-Umgebungen verwenden

Die App Check-Erzwingung basiert auf einer App Check SDK-Instanz, die von Firebase SDKs verwendet wird, um getToken intern aufzurufen. Das resultierende Token wird dann in Anfragen an alle Firebase-Dienste aufgenommen, sodass das Backend die App validieren kann.

Da das App Check SDK jedoch einen Browser benötigt, um auf bestimmte Heuristiken für die App-Validierung zuzugreifen, kann es nicht in Serverumgebungen initialisiert werden.

FirebaseServerApp bietet eine Alternative. Wenn bei der Initialisierung von FirebaseServerApp ein vom Client generiertes App Check-Token bereitgestellt wird, wird es von den Firebase-Produkt-SDKs beim Aufrufen von Firebase-Diensten verwendet. Eine App Check SDK-Instanz ist dann nicht erforderlich.

/// Next.js
import { initializeServerApp } from "firebase/app";

// Replace the following with your app's
// Firebase project configuration
const firebaseConfig = {
  // ...
};

const firebaseServerAppSettings = {
  appCheckToken: token // See "Pass client tokens to the server side
                       // rendering phase" for an example on how transmit
                       // the token from the client and the server.
}

const serverApp =
  initializeServerApp(firebaseConfig,
                      firebaseServerAppSettings);

// The App Check token will now be appended to all Firebase service requests.

Client-Tokens an die serverseitige Rendering-Phase übergeben

Verwenden Sie einen Service Worker, um authentifizierte Auth-ID-Tokens (und App Check-Tokens) vom Client an die serverseitige Rendering-Phase (SSR) zu übertragen. Bei diesem Ansatz werden Abrufanfragen abgefangen, die SSR auslösen, und die Tokens werden an die Anfrageheader angehängt.

Eine Referenzimplementierung eines Firebase Auth-Service Workers finden Sie unter Sitzungsverwaltung mit Service Workern. Unter Serverseitige Änderungen finden Sie Code, der zeigt, wie diese Tokens aus den Headern geparst werden, um sie für die FirebaseServerApp-Initialisierung zu verwenden.

Firestore in SSR-Umgebungen verwenden

Wenn Sie Webanwendungen mit serverseitigem Rendering (SSR) erstellen, müssen Sie häufig Daten zwischen dem Server und dem Client austauschen, um die Leistung und die Nutzerfreundlichkeit zu optimieren. Das Firestore SDK bietet Serialisierungstools, mit denen Sie Snapshots und bestimmte Datentypen auf dem Server erfassen und direkt an Ihre clientseitigen Komponenten übergeben können. Durch diesen Prozess werden redundante Abrufe vermieden, da der Client den Status mithilfe der während der SSR-Phase vorabgerufenen Daten aktualisieren kann. Außerdem können Sie von diesen serialisierten Zuständen zu Echtzeit-Listenern wechseln, damit Ihre Anwendung mit der Datenbank synchronisiert bleibt.

In diesem Abschnitt wird beschrieben, wie Sie Daten, die während der serverseitigen Renderingphase (SSR) abgerufen wurden, in clientseitigen Komponenten wiederverwenden.

Datentypen serialisieren

Bestimmte Firestore-Datentypen bieten eine toJSON-Methode, um ihre Daten in ein serialisierbares Format zu konvertieren. Dazu gehören Instanzen von Objekten wie Bytes, GeoPoint, Timestamp und VectorValue.

Sobald die Daten im JSON-Format vorliegen, können Sie sie über Standard-Framework-Mechanismen oder als Parameter an Komponenten, die die Grenze überschreiten, vom Server an den Client übergeben. Beispiel:

import {
  Bytes
} from 'firebase/firestore';

const BYTES_DATA = new Uint8Array([0, 1, 2, 3, 4, 5]);
const bytes = Bytes.fromUint8Array(BYTES_DATA);
const bytesJSON = bytes.toJSON();

Datentypen deserialisieren

Firestore-Datentypen enthalten die statische Methode fromJSON, um die serialisierten Daten in einen funktionsfähigen Firestore-Datentyp zu konvertieren.

Im folgenden Beispiel wird ein Bytes-Datentyp deserialisiert:

import {
  Bytes
} from 'firebase/firestore';

// Assuming the same `bytesJSON` variable from the previous example.
const deserializedBytes = Bytes.fromJSON(bytesJSON);

Firestore-Snapshots serialisieren und deserialisieren

Ähnlich wie bei Firestore-Datentypen können Sie Instanzen von DocumentSnapshot und QuerySnapshot mit toJSON serialisieren. Zum Deserialisieren müssen Sie jedoch die eigenständigen Funktionen documentSnapshotFromJSON und querySnapshotFromJSON anstelle einer statischen fromJSON-Methode verwenden.

Beispielsweise können die querySnapshot-Ergebnisse eines query-Vorgangs mit der Methode toJSON serialisiert werden:

import {
  collection,
  getDocs,
  query,
  querySnapshotFromJSON
} from 'firebase/firestore';
// Assuming a configured instance of Firestore in the variable `firestore`.
const queryRef = query(collection(firestore, QUERY_PATH));
const querySnapshot = await getDocs(queryRef);
const querySnapshotJson = querySnapshot.toJSON();

Anschließend können diese Daten deserialisiert werden:

import {
  querySnapshotFromJSON
} from 'firebase/firestore';

// deserializedSnapshot is an object of type QuerySnapshot:

const deserializedSnapshot =
  querySnapshotFromJSON(firestore, querySnapshotJson);

Listener mit serialisierten Snapshots

Die während der SSR-Phase abgefragten Daten sind zwar für das erste CSR-Rendering wertvoll, Sie müssen den Firestore-Dienst jedoch möglicherweise trotzdem auf Echtzeitaktualisierungen dieser Informationen überwachen.

Wenn Ihre App diese Echtzeitaktualisierungen benötigt, können Sie die Funktion onSnapshotResume verwenden, um Firestore-SnapshotListeners mit serialisierten Snapshot-Daten zu initialisieren. Beispiel:

const observer = {
  next: (qs) => {
    console.log("onSnapshot invoked: ", qs.data());
  },
  error: (e) => {
    console.log("error callback invoked: ", e.toString());
  }
};
const unsubscribe = onSnapshotResume(firestore, querySnapshotJson, observer);