Apps, die eine beliebige Firebase-Web-API mit Namespace verwenden, von den compat-Bibliotheken bis Version 8 oder früher, sollten gemäß der Anleitung in diesem Leitfaden zur modularen API migrieren.
In diesem Leitfaden wird davon ausgegangen, dass Sie mit der API mit Namensraum vertraut sind und einen Modul-Bundler wie webpack oder Rollup für das Upgrade und die laufende modulare App-Entwicklung verwenden.
Die Verwendung eines Modul-Bundlers in Ihrer Entwicklungsumgebung wird dringend empfohlen. Wenn Sie keinen verwenden, können Sie die Hauptvorteile der modularen API in Bezug auf die reduzierte App-Größe nicht nutzen. Sie benötigen npm oder yarn, um das SDK zu installieren.
Die Upgrade-Schritte in diesem Leitfaden basieren auf einer fiktiven Web-App, die die SDKs für Authentication und Cloud Firestore verwendet. Wenn Sie die Beispiele durcharbeiten, können Sie die Konzepte und praktischen Schritte beherrschen, die für das Upgrade aller unterstützten Firebase-Web-SDKs erforderlich sind.
Informationen zu den Bibliotheken mit Namespace (compat)
Für das Firebase-Web-SDK sind zwei Arten von Bibliotheken verfügbar:
- Modular : Eine neue API-Oberfläche, die das Tree Shaking (Entfernen von nicht verwendetem Code) erleichtert, um Ihre Web-App so klein und schnell wie möglich zu machen.
- Mit Namespace (
compat) : Eine vertraute API-Oberfläche, die vollständig mit den früheren Versionen des SDK kompatibel ist. So können Sie ein Upgrade durchführen, ohne den gesamten Firebase-Code auf einmal ändern zu müssen. Compat-Bibliotheken bieten im Vergleich zu ihren Pendants mit Namespace nur geringe oder gar keine Vorteile in Bezug auf Größe oder Leistung.
In diesem Leitfaden wird davon ausgegangen, dass Sie die Compat-Bibliotheken verwenden, um das Upgrade zu erleichtern. Mit diesen Bibliotheken können Sie weiterhin Code mit Namespace neben Code verwenden, der für die modulare API refaktoriert wurde. So können Sie Ihre App während des Upgrade-Prozesses einfacher kompilieren und debuggen.
Bei Apps mit einer sehr geringen Nutzung des Firebase-Web-SDK, z. B. einer App, die nur einen einfachen Aufruf an die Authentication APIs ausführt, kann es sinnvoll sein, älteren Code mit Namespace zu refaktorieren, ohne die Compat-Bibliotheken zu verwenden. Wenn Sie ein Upgrade für eine solche App durchführen, können Sie der Anleitung in diesem Leitfaden für die „modulare API“ folgen, ohne die Compat-Bibliotheken zu verwenden.
Informationen zum Upgrade-Prozess
Jeder Schritt des Upgrade-Prozesses ist so konzipiert, dass Sie die Bearbeitung des Quellcodes für Ihre App abschließen und sie dann ohne Fehler kompilieren und ausführen können. Zusammenfassend lässt sich sagen, dass Sie für das Upgrade einer App Folgendes tun müssen:
- Fügen Sie Ihrer App die modularen Bibliotheken und die Compat-Bibliotheken hinzu.
- Aktualisieren Sie die Importanweisungen in Ihrem Code auf „compat“.
- Refaktorieren Sie Code für ein einzelnes Produkt (z. B. Authentication) in den modularen Stil.
- Optional: Entfernen Sie an dieser Stelle die Authentication Compat-Bibliothek und den Compat-Code für Authentication, um die Vorteile in Bezug auf die App-Größe für Authentication zu nutzen, bevor Sie fortfahren.
- Refaktorieren Sie Funktionen für jedes Produkt (z. B. Cloud Firestore, FCM, usw.) in den modularen Stil und kompilieren und testen Sie sie, bis alle Bereiche abgeschlossen sind.
- Aktualisieren Sie den Initialisierungscode auf den modularen Stil.
- Entfernen Sie alle verbleibenden Compat-Anweisungen und den Compat-Code aus Ihrer App.
Neueste Version des SDK herunterladen
Laden Sie zuerst die modularen Bibliotheken und die Compat-Bibliotheken mit npm herunter:
npm i firebase@12.13.0 # OR yarn add firebase@12.13.0
Importe auf „compat“ aktualisieren
Damit Ihr Code nach dem Aktualisieren Ihrer Abhängigkeiten weiterhin funktioniert, ändern Sie die Importanweisungen so, dass die „compat“-Version jedes Imports verwendet wird. Beispiel:
Vorher: Version 8 oder früher
import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';
Nachher: compat
// compat packages are API compatible with namespaced code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';
In den modularen Stil refaktorieren
Während die APIs mit Namespace auf einem Namespace- und Dienstmuster mit Punktverkettung basieren, wird Ihr Code beim modularen Ansatz hauptsächlich um Funktionen organisiert. In der modularen API geben das Paket firebase/app und andere Pakete keinen umfassenden Export zurück, der alle Methoden aus dem Paket enthält. Stattdessen exportieren die Pakete einzelne Funktionen.
In der modularen API werden Dienste als erstes Argument übergeben und die Funktion verwendet dann die Details des Dienstes, um den Rest zu erledigen. Sehen wir uns an, wie das in zwei Beispielen funktioniert, in denen Aufrufe an die Authentication und Cloud Firestore APIs refaktoriert werden.
Beispiel 1: Authentication Funktion refaktorieren
Vorher: compat
Der Compat-Code ist mit dem Code mit Namespace identisch, aber die Importe haben sich geändert.
import firebase from "firebase/compat/app";
import "firebase/compat/auth";
const auth = firebase.auth();
auth.onAuthStateChanged(user => {
// Check for user status
});
Nachher: modular
Die Funktion getAuth verwendet firebaseApp als ersten Parameter.
Die onAuthStateChanged Funktion wird nicht von der auth Instanz verkettet, wie es in der API mit Namensraum der Fall wäre. Stattdessen ist sie eine kostenlose Funktion, die auth als ersten Parameter verwendet.
import { getAuth, onAuthStateChanged } from "firebase/auth";
const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
// Check for user status
});
Umgang mit der Auth-Methode getRedirectResult aktualisieren
Die modulare API führt eine nicht abwärtskompatible Änderung in getRedirectResult ein. Wenn kein Umleitungsvorgang aufgerufen wird, gibt die modulare API null zurück, im Gegensatz zur API mit Namensraum, die ein UserCredential mit einem null-Nutzer zurückgegeben hat.
Vorher: compat
const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
return null;
}
return result;
Nachher: modular
const result = await getRedirectResult(auth);
// Provider of the access token could be Facebook, Github, etc.
if (result === null || provider.credentialFromResult(result) === null) {
return null;
}
return result;
Beispiel 2: eine Cloud Firestore Funktion refaktorieren
Vorher: compat
import "firebase/compat/firestore"
const db = firebase.firestore();
db.collection("cities").where("capital", "==", true)
.get()
.then((querySnapshot) => {
querySnapshot.forEach((doc) => {
// doc.data() is never undefined for query doc snapshots
console.log(doc.id, " => ", doc.data());
});
})
.catch((error) => {
console.log("Error getting documents: ", error);
});
Nachher: modular
Die Funktion getFirestore verwendet firebaseApp als ersten Parameter, der in einem früheren Beispiel von initializeApp zurückgegeben wurde. Beachten Sie, dass sich der Code zum Erstellen einer Abfrage in der modularen API stark unterscheidet. Es gibt keine Verkettung und Methoden wie query oder where werden jetzt als kostenlose Funktionen verfügbar gemacht.
import { getFirestore, collection, query, where, getDocs } from "firebase/firestore";
const db = getFirestore(firebaseApp);
const q = query(collection(db, "cities"), where("capital", "==", true));
const querySnapshot = await getDocs(q);
querySnapshot.forEach((doc) => {
// doc.data() is never undefined for query doc snapshots
console.log(doc.id, " => ", doc.data());
});
Verweise auf Firestore DocumentSnapshot.exists aktualisieren
Die modulare API führt eine nicht abwärtskompatible Änderung ein, bei der die Property firestore.DocumentSnapshot.exists in eine Methode geändert wurde. Die Funktionalität ist im Wesentlichen dieselbe (Testen, ob ein Dokument vorhanden ist), aber Sie müssen Ihren Code so refaktorieren, dass die neuere Methode verwendet wird:
Vorher:compat
if (snapshot.exists) {
console.log("the document exists");
}
Nachher: modular
if (snapshot.exists()) {
console.log("the document exists");
}
Beispiel 3: Code-Stile mit Namespace und modular kombinieren
Wenn Sie die Compat-Bibliotheken während des Upgrades verwenden, können Sie weiterhin Code mit Namespace neben Code verwenden, der für die modulare API refaktoriert wurde. So können Sie vorhandenen Code mit Namespace für Cloud Firestore beibehalten, während Sie Authentication oder anderen Firebase-SDK-Code in den modularen Stil refaktorieren, und Ihre App trotzdem mit beiden Code- Stilen kompilieren. Dasselbe gilt für API-Code mit Namespace und modularen API-Code innerhalb eines Produkts wie Cloud Firestore. Neue und alte Code-Stile können nebeneinander existieren, solange Sie die Compat-Pakete importieren:
import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'
const docRef = firebase.firestore().doc();
getDoc(docRef);
Beachten Sie, dass Ihre App zwar kompiliert wird, Sie aber die Vorteile des modularen Codes in Bezug auf die App-Größe erst nutzen können, wenn Sie die Compat-Anweisungen und den Compat-Code vollständig aus Ihrer App entfernt haben.
Initialisierungscode aktualisieren
Aktualisieren Sie den Initialisierungscode Ihrer App, um die modulare Syntax zu verwenden. Es ist
wichtig, diesen Code zu aktualisieren, nachdem Sie das Refactoring des gesamten
Codes in Ihrer App abgeschlossen haben. Das liegt daran, dass firebase.initializeApp() den globalen
Status sowohl für die Compat- als auch für die modularen APIs initialisiert, während die modulare
initializeApp() Funktion nur den Status für die modulare API initialisiert.
Vorher: compat
import firebase from "firebase/compat/app"
firebase.initializeApp({ /* config */ });
Nachher: modular
import { initializeApp } from "firebase/app"
const firebaseApp = initializeApp({ /* config */ });
Compat-Code entfernen
Um die Vorteile der modularen API in Bezug auf die Größe zu nutzen, sollten Sie schließlich
alle Aufrufe in den oben gezeigten modularen Stil konvertieren und alle
import "firebase/compat/* Anweisungen aus Ihrem Code entfernen. Wenn Sie fertig sind, sollten keine Verweise mehr auf den globalen Namespace firebase.* oder anderen Code im Stil der API mit Namensraum vorhanden sein.
Compat-Bibliothek aus dem Fenster verwenden
Die modulare API ist für die Verwendung mit Modulen und nicht mit dem window-Objekt des Browsers optimiert. In früheren Versionen der Bibliothek konnten Firebase-Bibliotheken mit dem Namespace window.firebase geladen und verwaltet werden. Das wird in Zukunft nicht mehr empfohlen, da nicht verwendeter Code nicht entfernt werden kann.
Die Compat-Version des JavaScript SDK funktioniert jedoch mit dem window-Objekt für Entwickler, die nicht sofort mit dem modularen Upgrade beginnen möchten.
<script src="https://www.gstatic.com/firebasejs/12.13.0/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/12.13.0/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/12.13.0/firebase-auth-compat.js"></script>
<script>
const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
const db = firebaseApp.firestore();
const auth = firebaseApp.auth();
</script>
Die Compat-Bibliothek verwendet modularen Code im Hintergrund und bietet dieselbe API wie die API mit Namensraum. Das bedeutet, Sie können in der API-Referenz zur API mit Namensraum und in den Code-Snippets mit Namensraum nach Details suchen. Diese Methode wird nicht für die langfristige Verwendung empfohlen, sondern als Einstieg in das Upgrade auf die vollständig modulare Bibliothek.
Vorteile und Einschränkungen des modularen SDK
Das vollständig modularisierte SDK bietet gegenüber früheren Versionen folgende Vorteile:
- Das modulare SDK ermöglicht eine drastische Reduzierung der App-Größe. Es verwendet das moderne JavaScript-Modulformat, das Tree Shaking ermöglicht. Dabei werden nur die Artefakte importiert, die Ihre App benötigt. Je nach App kann Tree Shaking mit dem modularen SDK zu einer um 80% geringeren Größe in Kilobyte führen als bei einer vergleichbaren App, die mit der API mit Namensraum erstellt wurde.
- Das modulare SDK wird weiterhin von der laufenden Funktionsentwicklung profitieren, die API mit Namensraum jedoch nicht.