Les applications utilisant actuellement Firebase Web SDK version 8 ou antérieure doivent envisager de migrer vers la version 9 en suivant les instructions de ce guide.
Ce guide suppose que vous êtes familiarisé avec la version 8 et que vous tirerez parti d'un bundle de modules tel que webpack ou Rollup pour la mise à niveau et le développement continu de la version 9.
L'utilisation d'un module bundler dans votre environnement de développement est fortement recommandée. Si vous n'en utilisez pas, vous ne pourrez pas profiter des principaux avantages de la version 9 en termes de taille d'application réduite. Vous aurez besoin de npm ou de yarn pour installer le SDK.
Les étapes de mise à niveau de ce guide seront basées sur une application Web imaginaire qui utilise les SDK d'authentification et Cloud Firestore. En travaillant sur les exemples, vous pouvez maîtriser les concepts et les étapes pratiques nécessaires pour mettre à niveau tous les SDK Web Firebase pris en charge.
À propos des bibliothèques de compatibilité
Deux types de bibliothèques sont disponibles pour la version 9 du SDK Web Firebase :
- Modulaire - une nouvelle surface d'API conçue pour faciliter le tree-shaking (suppression du code inutilisé) afin de rendre votre application Web aussi petite et rapide que possible.
- Compat - une surface d'API familière qui est entièrement compatible avec la version 8 du SDK, vous permettant de passer à la version 9 sans modifier tout votre code Firebase à la fois. Les bibliothèques Compat ont peu ou pas d'avantages en termes de taille ou de performances par rapport à leurs homologues de la version 8.
Ce guide suppose que vous profiterez des bibliothèques compatibles de la version 9 pour faciliter votre mise à niveau. Ces bibliothèques vous permettent de continuer à utiliser le code de la version 8 parallèlement au code refactorisé pour la version 9. Cela signifie que vous pouvez compiler et déboguer votre application plus facilement au cours du processus de mise à niveau.
Pour les applications très peu exposées au SDK Web Firebase - par exemple, une application qui ne fait qu'un simple appel aux API d'authentification - il peut être pratique de refactoriser le code de la version 8 sans utiliser les bibliothèques compatibles de la version 9. Si vous mettez à niveau une telle application, vous pouvez suivre les instructions de ce guide pour la "version 9 modulaire" sans utiliser les bibliothèques de compatibilité.
À propos du processus de mise à niveau
Chaque étape du processus de mise à niveau est définie de manière à ce que vous puissiez terminer la modification de la source de votre application, puis la compiler et l'exécuter sans interruption. En résumé, voici ce que vous ferez pour mettre à jour une application :
- Ajoutez les bibliothèques de la version 9 et les bibliothèques de compatibilité à votre application.
- Mettez à jour les instructions d'importation dans votre code vers la compatibilité v9.
- Refactorisez le code d'un seul produit (par exemple, l'authentification) dans le style modulaire.
- Facultatif : à ce stade, supprimez la bibliothèque de compatibilité d'authentification et le code de compatibilité pour l'authentification afin de réaliser l'avantage de la taille de l'application pour l'authentification avant de continuer.
- Refactorisez les fonctions de chaque produit (par exemple, Cloud Firestore, FCM, etc.) dans le style modulaire, en compilant et en testant jusqu'à ce que tous les domaines soient terminés.
- Mettez à jour le code d'initialisation au style modulaire.
- Supprimez toutes les déclarations de compatibilité restantes de la version 9 et le code de compatibilité de votre application.
Obtenir le SDK de la version 9
Pour commencer, obtenez les bibliothèques de la version 9 et les bibliothèques compatibles à l'aide de npm :
npm i firebase@9.17.1 # OR yarn add firebase@9.17.1
Mettre à jour les importations vers la compatibilité v9
Afin de maintenir le fonctionnement de votre code après la mise à jour de votre dépendance de la v8 à la v9 bêta, modifiez vos instructions d'importation pour utiliser la version "compat" de chaque importation. Par exemple:
Avant : version 8
import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';
Après : version 9 compatible
// v9 compat packages are API compatible with v8 code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';
Refactoriser au style modulaire
Alors que les API de la version 8 sont basées sur un espace de noms et un modèle de service chaînés par des points, l'approche modulaire de la version 9 signifie que votre code sera principalement organisé autour de fonctions . Dans la version 9, le firebase/app et les autres packages ne renvoient pas d'exportation complète contenant toutes les méthodes du package. Au lieu de cela, les packages exportent des fonctions individuelles.
Dans la version 9, les services sont passés en premier argument, et la fonction utilise ensuite les détails du service pour faire le reste. Examinons comment cela fonctionne dans deux exemples qui refactorisent les appels vers les API d'authentification et Cloud Firestore.
Exemple 1 : refactoring d'une fonction d'authentification
Avant : version 9 compatible
Le code de compatibilité de la version 9 est identique au code de la version 8, mais les importations ont changé.
import firebase from "firebase/compat/app";
import "firebase/compat/auth";
const auth = firebase.auth();
auth.onAuthStateChanged(user => {
// Check for user status
});
Après : version 9 modulaire
La fonction getAuth prend firebaseApp comme premier paramètre. La fonction onAuthStateChanged n'est pas chaînée à partir de l'instance auth comme elle le serait dans la version 8 ; à la place, c'est une fonction libre qui prend auth comme premier paramètre.
import { getAuth, onAuthStateChanged } from "firebase/auth";
const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
// Check for user status
});
Mise à jour de la gestion de la méthode Auth getRedirectResult
La version 9 introduit une modification avec rupture dans getRedirectResult . Lorsqu'aucune opération de redirection n'est appelée, la version 9 renvoie null , contrairement à la version 8, qui renvoyait un UserCredential avec un utilisateur null .
Avant : version 9 compatible
const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
return null;
}
return result;
Après : version 9 modulaire
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;
Exemple 2 : refactoriser une fonction Cloud Firestore
Avant : version 9 compatible
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);
});
Après : version 9 modulaire
La fonction getFirestore prend firebaseApp comme premier paramètre, qui a été renvoyé par initializeApp dans un exemple précédent. Notez que le code pour former une requête est très différent dans la version 9 ; il n'y a pas de chaînage et des méthodes telles que query ou where sont maintenant exposées en tant que fonctions libres.
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());
});
Mettre à jour les références à Firestore DocumentSnapshot.exists
La version 9 introduit une modification radicale dans laquelle la propriété firestore.DocumentSnapshot.exists a été remplacée par une méthode . La fonctionnalité est essentiellement la même (tester si un document existe) mais vous devez refactoriser votre code pour utiliser la méthode v9 comme indiqué :
Avant : version 9 compatible
if (snapshot.exists) {
console.log("the document exists");
}
Après : version 9 modulaire
if (snapshot.exists()) {
console.log("the document exists");
}
Exemple 3 : combinaison des styles de code version 8 et version 9
L'utilisation des bibliothèques compat pendant la mise à niveau vous permet de continuer à utiliser le code de la version 8 parallèlement au code refactorisé pour la version 9. Cela signifie que vous pouvez conserver le code de la version 8 existant pour Cloud Firestore pendant que vous refactorisez l'authentification ou un autre code du SDK Firebase au style de la version 9, et toujours compilez avec succès votre application avec les deux styles de code. Il en va de même pour le code des versions 8 et 9 dans un produit tel que Cloud Firestore ; les nouveaux et anciens styles de code peuvent coexister, tant que vous importez les packages compatibles :
import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'
const docRef = firebase.firestore().doc();
getDoc(docRef);
Gardez à l'esprit que, bien que votre application soit compilée, vous n'obtiendrez pas les avantages de taille d'application du code modulaire tant que vous n'aurez pas entièrement supprimé les instructions de compatibilité et le code de votre application.
Mettre à jour le code d'initialisation
Mettez à jour le code d'initialisation de votre application pour utiliser la nouvelle syntaxe modulaire de la version 9. Il est important de mettre à jour ce code une fois que vous avez terminé de refactoriser tout le code de votre application ; c'est parce que firebase.initializeApp() initialise l'état global pour les API compat et modulaire, alors que la fonction modular initializeApp() initialise uniquement l'état pour modular.
Avant : version 9 compatible
import firebase from "firebase/compat/app"
firebase.initializeApp({ /* config */ });
Après : version 9 modulaire
import { initializeApp } from "firebase/app"
const firebaseApp = initializeApp({ /* config */ });
Supprimer le code de compatibilité
Pour tirer parti des avantages de taille du SDK modulaire de la version 9, vous devez éventuellement convertir toutes les invocations dans le style modulaire indiqué ci-dessus et supprimer toutes les instructions d' import "firebase/compat/* de votre code. Lorsque vous avez terminé, il ne devrait pas y avoir plus de références à l'espace de noms global firebase.* ou à tout autre code dans le style SDK de la version 8.
Utilisation de la bibliothèque comp depuis la fenêtre
Le SDK version 9 est optimisé pour fonctionner avec des modules plutôt qu'avec l'objet window du navigateur. Les versions précédentes de la bibliothèque permettaient le chargement et la gestion de Firebase en utilisant l'espace de noms window.firebase . Ceci n'est pas recommandé à l'avenir car cela ne permet pas d'éliminer le code inutilisé. Cependant, la version compatible du SDK JavaScript fonctionne avec la window pour les développeurs qui préfèrent ne pas commencer immédiatement le chemin de mise à niveau modulaire.
<script src="https://www.gstatic.com/firebasejs/9.17.1/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.17.1/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.17.1/firebase-auth-compat.js"></script>
<script>
const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
const db = firebaseApp.firestore();
const auth = firebaseApp.auth();
</script>
La bibliothèque de compatibilité utilise le code modulaire de la version 9 sous le capot et lui fournit la même API que la version 8 du SDK ; cela signifie que vous pouvez vous référer à la référence de l' API version 8 et aux extraits de code de la version 8 pour plus de détails. Cette méthode n'est pas recommandée pour une utilisation à long terme, mais comme un début de mise à niveau vers la bibliothèque entièrement modulaire de la version 9.
Avantages et limites de la version 9
La version 9 entièrement modularisée présente ces avantages par rapport aux versions précédentes :
- La version 9 permet une taille d'application considérablement réduite. Il adopte le format de module JavaScript moderne, permettant des pratiques de « tree shaking » dans lesquelles vous n'importez que les artefacts dont votre application a besoin. Selon votre application, le tree-shaking avec la version 9 peut entraîner 80 % de kilo-octets en moins qu'une application comparable construite avec la version 8.
- La version 9 continuera de bénéficier du développement continu des fonctionnalités, tandis que la version 8 sera gelée à un moment donné dans le futur.