Passer au SDK Web modulaire (v9)

Nous recommandons aux applications qui utilisent le SDK Web 8 ou une version antérieure de passer à la version 9 en suivant les instructions de ce guide.

Dans ce guide, nous partons du principe que vous connaissez la version 8 et que vous allez tirer parti d'un bundler 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 bundler de module 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 réduisant la taille de l'application. Vous avez besoin de npm ou de yarn pour installer le SDK.

À propos des bibliothèques compat

Deux types de bibliothèques sont disponibles pour le SDK Web version 9:

  • Modulaire : nouvelle surface d'API conçue pour faciliter le tremblement d'arborescence (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, ce qui vous permet de passer à la version 9 sans modifier tout le code de votre SDK en même temps. Les bibliothèques Compat n'offrent que peu ou pas d'avantages en termes de taille ou de performances par rapport à leurs homologues de la version 8.

Dans ce guide, nous partons du principe que vous allez tirer parti des bibliothèques compat de la version 9 pour faciliter votre mise à niveau. Ces bibliothèques vous permettent de continuer à utiliser le code de la version 8, ainsi que le code refactorisé pour la version 9. Cela signifie que vous pouvez compiler et déboguer votre application plus facilement pendant le 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 compat 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 compat.

À propos du processus de mise à niveau

Chaque étape du processus de mise à niveau est définie de sorte que vous puissiez terminer de modifier la source de votre application, puis la compiler et l'exécuter sans interruption. En résumé, voici comment procéder pour mettre à jour une application:

  1. Ajoutez les bibliothèques de la version 9 et les bibliothèques compat à votre application.
  2. Mettez à jour les instructions d'importation dans votre code vers la compatibilité v9.
  3. Refactorisez le code pour le rendre modulaire.
  4. Supprimez la bibliothèque de compatibilité d'Authentication et le code de compatibilité pour Authentication afin de profiter des avantages en termes de taille d'application.
  5. Mettez à jour le code d'initialisation vers le style modulaire.
  6. Supprimez toutes les instructions de compatibilité de la version 9 restantes et le code de compatibilité de votre application.

Obtenir le SDK version 9

Pour commencer, récupérez 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@10.12.0

# OR

yarn add firebase@10.12.0

Mettre à jour les importations vers la version 9

Pour que votre code fonctionne après la mise à jour de votre dépendance de la version 8 à la version 9, modifiez vos instructions d'importation pour qu'elles utilisent la version "compat" de chaque importation. Exemple :

Avant: version 8

import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';

Après: version 9 compat

// v9 compat packages are API compatible with v8 code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';

Refactoriser 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 reliés par 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 d'exportation complète contenant toutes les méthodes du package. À la place, 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: refactoriser une fonction d'authentification simple

Avant: version 9 compat

Le code de compatibilité de la version 9 est identique au code 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, en plus du 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 9 modulaire

La fonction getAuth utilise firebaseApp comme premier paramètre. La fonction onAuthStateChanged n'est pas enchaînée à l'instance auth comme elle le serait dans la version 8. Il s'agit 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
});

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 après avoir fini de refactoriser tout le code de votre application. En effet, firebase.initializeApp() initialise l'état global pour les API de compatibilité et les API modulaires, tandis que la fonction modulaire initializeApp() n'initialise que l'état des API modulaires.

Avant: version 9 compat

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 profiter des avantages en termes de taille du SDK modulaire version 9, vous devez à terme convertir tous les appels dans le style modulaire présenté ci-dessus et supprimer toutes les instructions import "firebase/compat/* de votre code. Lorsque vous avez terminé, il ne doit plus y avoir de références à l'espace de noms global firebase.* ni à aucun autre code du style du SDK version 8.

Avantages et limites de la version 9

La version 9 entièrement modularisée 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 les 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 une réduction de 80% du nombre de kilo-octets par rapport à une application comparable créée avec la version 8.
  • La version 9 continuera de bénéficier du développement continu de fonctionnalités, tandis que la version 8 sera bloquée à un moment donné.