Cette page propose des conseils et des solutions pour résoudre les problèmes JavaScript que vous pourriez rencontrer lors de l'utilisation du SDK Firebase JavaScript.
Vous rencontrez d'autres difficultés ou vous ne trouvez pas votre problème ? N'oubliez pas de consulter les questions fréquentes principales sur Firebase pour en savoir plus sur Firebase en général ou sur des produits spécifiques.
Vous pouvez également consulter le dépôt GitHub du SDK Firebase JavaScript pour obtenir une liste à jour des problèmes signalés et des solutions de dépannage, et y signaler vos propres problèmes.
Les constructions Admin SDK pour Node.js ne sont pas compatibles avec le SDK JavaScript Firebase.
Firebase Admin SDK pour Node.js et le SDK Firebase JavaScript sont des implémentations distinctes qui ne partagent pas de définitions d'interface, de classe ni de fonction. Les instances d'objets Admin SDK ne sont pas compatibles avec les fonctions du SDK JavaScript Firebase.
Par exemple, une instance de FirebaseApp de Admin SDK transmise à la fonction getDatabase du SDK Firebase JavaScript génère l'erreur suivante :
TypeError: Cannot read properties of undefined (reading 'getProvider')
at _getProvider
at getDatabase
Cela s'applique à l'ensemble de la surface de l'API du SDK Firebase JavaScript, et pas seulement à Realtime Database.
Cela vaut également pour l'utilisation dans le sens inverse. Toute tentative d'utilisation du type Timestamp du SDK JS Cloud Firestore avec Firebase Admin SDK pour Node.js génère des erreurs similaires.
Évitez d'utiliser des versions incompatibles du SDK Firebase JavaScript
Si plusieurs versions conflictuelles du SDK Firebase JavaScript sont configurées en tant que dépendances dans un projet, des erreurs d'exécution se produiront lorsque des instances de SDK seront transmises entre des packages de SDK. Par exemple, l'utilisation de la bibliothèque Data Connect avec une version incompatible de FirebaseApp entraîne l'erreur suivante :
Error: Component data-connect has not been registered yet
Ce problème est généralement dû à une mise à jour des dépendances de l'un des packages du SDK Firebase, mais pas de tous. Cette situation se produit souvent lorsqu'un outil de mise à jour automatique des dépendances modifie un sous-ensemble des dépendances du SDK Firebase dans le fichier yarn.lock ou package-lock.json du projet. Étant donné que de nombreux SDK Firebase JavaScript interagissent les uns avec les autres, l'utilisation de différentes versions des SDK entraîne des incompatibilités d'exécution.
Pour résoudre ce problème, supprimez le répertoire node_modules/ et le fichier yarn.lock (pour yarn) ou package-lock.json (pour npm) dans votre projet, puis réinstallez vos dépendances.
Si des erreurs persistent, déboguez le problème à l'aide de la commande npm ls. Cela enregistre les dépendances de votre projet afin que vous puissiez identifier les versions conflictuelles du module firebase.
Par exemple, le journal suivant montre package-using-older-firebase important une version conflictuelle du SDK Firebase JavaScript :
$ npm ls firebase --all
your-app@0.0.0
├── firebase@11.2.0
├─┬ @angular/fire@19.0.0
│ ├── firebase@11.2.0 deduped
│ └─┬ rxfire@6.1.0
│ └── firebase@10.14.1 deduped
└─┬ package-using-older-firebase@0.1.0
└─── firebase@10.14.1
Des erreurs peuvent également se produire si vous mélangez les instructions require et import de CJS et d'ESM dans votre application. Cela crée plusieurs instances du SDK Firebase JavaScript, chacune distincte des autres, ce qui interrompt l'interopérabilité du SDK Firebase JavaScript.
Augmentez le niveau de détail de votre outil de regroupement de choix pour déboguer ce scénario. Par exemple, vous pouvez utiliser l'indicateur d'analyse esbuild à cette fin.
Assurez-vous que les service workers sont regroupés
Les service workers sont souvent créés à partir d'un pipeline distinct du reste d'une application Web et ne sont pas inclus dans la configuration par défaut des bundlers tels que Webpack.
Si vous utilisez la version modulaire du SDK Firebase JavaScript dans votre service worker, assurez-vous de configurer votre bundler d'application pour inclure le fichier source du service worker. L'exemple suivant utilise npx pour regrouper le service worker firebase-sw.js dans le répertoire src du projet :
npx esbuild ./src/firebase-sw.js --bundle --minify --main-fields=webworker,browser,module,main,default --outfile=public/firebase-sw.js
L'activation d'un service worker non groupé échouera s'il importe des modules ES qui ne sont pas compatibles avec les service workers ou des fichiers qui n'existent pas dans le champ d'application du service worker. Parfois, ces échecs sont silencieux et difficiles à déboguer.
Pour en savoir plus sur le regroupement de la version modulaire du SDK Firebase JavaScript dans votre application, consultez Utiliser des bundlers de modules avec Firebase.
Vous pouvez également éviter le regroupement en important les bundles SDK compat
Firebase JavaScript à partir du CDN :
// Give the service worker access to Firebase Messaging.
// Replace 10.13.2 with the version of the Firebase JS SDK you're using
// in your app.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.js');
// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
...
});
// Retrieve an instance of Firebase Messaging so that it can handle
// background messages.
const messaging = firebase.messaging();
Utiliser FirebaseServerApp avec le rendu côté serveur
Le SDK Firebase JavaScript était initialement conçu pour s'exécuter dans des environnements de navigateur. L'introduction de frameworks de rendu côté serveur (SSR) pousse l'utilisation du SDK dans de nouveaux environnements d'exécution. Ces environnements d'exécution fournissent un sous-ensemble d'outils et d'API fournis par les navigateurs Web.
Par exemple, certains SDK Firebase nécessitent la mise en cache des données avec IndexedDB, une API réservée aux navigateurs. Firebase Auth peut nécessiter une interaction de l'utilisateur dans certains flux de connexion, ce qui est impossible dans les environnements de serveur sans interface graphique. App Check s'appuie sur des heuristiques de navigateur pour valider l'utilisateur avant de créer des jetons App Check.
Lorsque vous utilisez le SDK dans ces nouveaux environnements, utilisez FirebaseServerApp, une nouvelle variante de FirebaseApp qui permet de précharger l'instance Firebase SSR avec les données collectées côté client.
FirebaseServerApp accepte deux paramètres :
- Jeton d'identification Auth : si ce jeton est fourni, Firebase Auth connecte automatiquement un utilisateur précédemment authentifié, ce qui peut permettre de maintenir une session au-delà de la séparation CSR/SSR.
- Jeton App Check : s'il est fourni, le jeton est utilisé par les autres SDK Firebase sans qu'il soit nécessaire d'initialiser une instance d'un client App Check (qui n'est pas compatible en dehors des environnements de navigateur). Cela permet de débloquer la prise en charge du SSR pour les produits pour lesquels App Check est activé, tels que Cloud Functions, Data Connect, Cloud Firestore, Realtime Database et Vertex AI.
Pour obtenir un exemple d'utilisation de FirebaseServerApp dans Next.js, consultez Simplifier le développement d'applications SSR avec FirebaseServerApp.