Passer au SDK Web modulaire (v9)
Les applications qui utilisent actuellement la version 8 ou antérieure du SDK Web devraient envisager de passer à la version 9 en suivant les instructions de ce guide.
Ce guide part du principe que vous connaissez la version 8 et que vous utiliserez un outil de regroupement de modules tel que webpack ou Rollup pour la mise à niveau et le développement continu de la version 9.
Nous vous recommandons vivement d'utiliser un outil de regroupement de modules dans votre environnement de développement. Si vous n'en utilisez pas, vous ne pourrez pas profiter des principaux avantages de la version 9 en termes de réduction de la taille de l'application. Vous aurez besoin de npm ou de yarn pour installer le SDK.
À propos des bibliothèques de compatibilité
Deux types de bibliothèques sont disponibles pour la version 9 du SDK Web:
- Modular : 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 : surface d'API familière entièrement compatible avec la version 8, qui vous permet de passer à la version 9 sans modifier l'ensemble de votre code de SDK en une seule fois. Les bibliothèques de compatibilité présentent 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 utiliserez les bibliothèques de compatibilité de la version 9 pour faciliter la mise à niveau. Ces bibliothèques vous permettent de continuer à utiliser le code de la version 8 avec le 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 ayant une très faible exposition au SDK Web, il peut être pratique de refactoriser le code de la version 8 sans utiliser les bibliothèques de compatibilité de la version 9. Si vous mettez à niveau une telle application, vous pouvez suivre les instructions de ce guide pour la "version modulaire 9" sans utiliser les bibliothèques de compatibilité.
À propos du processus de mise à niveau
Chaque étape du processus de mise à niveau est limitée afin 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 devez faire pour mettre à niveau une application:
- Ajoutez les bibliothèques de la version 9 et les bibliothèques de compatibilité à votre application.
- Mettez à jour les instructions d'importation de votre code pour qu'elles soient compatibles avec la version 9.
- Refactorisez le code en style modulaire.
- Supprimez la bibliothèque de compatibilité d'authentification et le code de compatibilité pour l'authentification afin de profiter de l'avantage de taille de l'application.
- Mettez à jour le code d'initialisation en adoptant le style modulaire.
- Supprimez toutes les instructions de compatibilité de la version 9 et le code de compatibilité restants de votre application.
Obtenir le SDK de la version 9
Pour commencer, téléchargez les bibliothèques de la version 9 et les bibliothèques de compatibilité à l'aide de npm (dernière version : https://www.npmjs.com/package/firebase) :
npm i firebase@11.1.0
# OR
yarn add firebase@11.1.0
Mise à jour des importations pour la compatibilité avec la version 9
Pour que votre code continue de fonctionner après la mise à niveau de votre dépendance de la version 8 à la version 9, modifiez vos instructions d'importation pour utiliser la version "compat" de chaque importation. Exemple :
Avant: version 8
import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';
Après: compatibilité avec la version 9
// v9 compat packages are API compatible with v8 code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';
Refactorisation vers le style modulaire
Alors que les API de la version 8 sont basées sur un espace de noms et un modèle de service en chaîne de points, l'approche modulaire de la version 9 signifie que votre code sera principalement organisé autour de fonctions. Dans la version 9, le package firebase/app et les autres packages ne renvoient pas une 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 transmis en tant que premier argument, et la fonction utilise ensuite les détails du service pour effectuer le reste.
Exemple: refactorisation d'une fonction d'authentification simple
Avant: compatibilité avec la version 9
Le code de compatibilité de la version 9 est identique à celui de la version 8, mais les importations ont changé. L'utilisation des bibliothèques de compatibilité lors de la mise à niveau vous permet de continuer à utiliser le code de la version 8 avec le code refactorisé pour la version 9.
import firebase from "firebase/compat/app";
import "firebase/compat/auth";
const auth = firebase.auth();
auth.onAuthStateChanged(user => {
// Check for user status
});
Après: version modulaire 9
La fonction getAuth utilise firebaseApp comme premier paramètre. La fonction onAuthStateChanged n'est pas enchaînée à partir de l'instance d'authentification comme elle le serait dans la version 8. Il s'agit plutôt d'une fonction libre qui utilise auth comme premier paramètre.
import { getAuth, onAuthStateChanged } from "firebase/auth";
const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
// Check for user status
});
Modifier le code d'initialisation
Mettez à jour le code d'initialisation de votre application pour qu'il utilise la nouvelle syntaxe modulaire de la version 9. Il est important de mettre à jour ce code après avoir terminé de refactoriser tout le code de votre application. En effet, firebase.initializeApp() initialise l'état global à la fois pour les API de compatibilité et modulaires, tandis que la fonction initializeApp() modulable n'initialise que l'état pour le modulaire.
Avant: compatibilité avec la version 9
import firebase from "firebase/compat/app"
firebase.initializeApp({ /* config */ });
Après: version modulaire 9
import { initializeApp } from "firebase/app"
const firebaseApp = initializeApp({ /* config */ });
Supprimer le code de compatibilité
Pour profiter des avantages de taille du SDK modulaire de la version 9, vous devez éventuellement convertir toutes les invocations au style modulaire illustré ci-dessus et supprimer toutes les instructions import "firebase/compat/* de votre code. Lorsque vous avez terminé, il ne devrait plus y avoir de références à l'espace de noms global firebase.* ni à aucun autre code dans le style du SDK de la version 8.
Avantages et limites de la version 9
La version 9 entièrement modulaire présente les avantages suivants par rapport aux versions précédentes:
- La version 9 permet de réduire considérablement la taille de l'application. Il adopte le format de module JavaScript moderne, ce qui permet de pratiquer le "tree shaking", c'est-à-dire d'importer uniquement les artefacts dont votre application a besoin. Selon votre application, le tree-shaking avec la version 9 peut réduire la taille de votre application de 80% par rapport à une application comparable créée avec la version 8.
- La version 9 continuera de bénéficier du développement de fonctionnalités, tandis que la version 8 sera figée à un moment donné.