Passer au SDK Web modulaire (v9)

Les applications qui utilisent actuellement la version 8 du SDK Web ou une version antérieure doivent envisager de migrer vers la version 9 en suivant les instructions de ce guide.

Ce guide part du principe que vous connaissez la version 8 et que vous allez utiliser 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 la version 9 du SDK Web:

  • Modular : 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, qui vous permet de passer à la version 9 sans modifier tout le code de votre SDK en même temps. Les bibliothèques Compat présentent 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 exploiter les bibliothèques compatibles de la version 9 pour faciliter la 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 fur et à mesure du processus de mise à niveau.

Pour les applications dont l'exposition au SDK Web est très faible, 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 concernant 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 pour que vous puissiez terminer la modification du code source de votre application, puis la compiler et l'exécuter sans problème. En résumé, voici ce que vous devez faire pour mettre à niveau 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 de votre code vers la compatibilité v9.
  3. Refactorisez le code pour le convertir en style modulaire.
  4. Supprimez la bibliothèque de compatibilité d'Authentication et le code de compatibilité pour l'authentification afin de bénéficier de l'avantage lié à la taille de l'application.
  5. Mise à jour du 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 la version 9 du SDK

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.2

# OR

yarn add firebase@10.12.2

Mettre à jour les importations vers la compatibilité v9

Pour que votre code continue de fonctionner 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: compatibilité 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';

Refactoriser pour adopter un style modulaire

Alors que les API version 8 sont basées sur un modèle de service et un espace de noms en pointillés, 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. Au lieu de cela, les packages exportent des fonctions individuelles.

Dans la version 9, les services sont transmis en tant que premier argument. La fonction utilise ensuite les détails du service pour faire le reste.

Exemple: refactoriser une fonction Authentication simple

Avant: compatibilité 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 9 modulaire

La fonction getAuth utilise firebaseApp comme premier paramètre. La fonction onAuthStateChanged n'est pas chaînée à partir de l'instance d'authentification comme dans la version 8. Il s'agit plutôt d'une fonction gratuite 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 (version 9). Il est important de mettre à jour ce code après avoir refactorisé tout le code de votre application. En effet, firebase.initializeApp() initialise l'état global pour les API de compatibilité et modulaires, tandis que la fonction modulaire initializeApp() n'initialise que l'état pour les API modulaires.

Avant: compatibilité version 9

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 devrait plus y avoir de références à l'espace de noms global firebase.* ni à tout autre code dans le 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 antérieures:

  • La version 9 permet de réduire considérablement la taille des applications. Il adopte le format de module JavaScript moderne, ce qui permet d'appliquer des pratiques de "tree shaking" dans lesquelles vous n'importez que les artefacts dont votre application a besoin. Selon votre application, les tremblements d'arborescence avec la version 9 peuvent entraîner 80% de kilo-octets en moins par rapport à une application comparable créée avec la version 8.
  • La version 9 continuera à bénéficier du développement continu des fonctionnalités, tandis que la version 8 sera figée à un moment donné.