Prácticas recomendadas del SDK de Firebase JavaScript

En esta página, se ofrecen sugerencias y soluciones para problemas de JavaScript que puedes encontrar cuando usas el SDK de Firebase JavaScript.

¿Tienes otros desafíos o no ves tu problema? Asegúrate de consultar las Preguntas frecuentes principales de Firebase para obtener más información general o específica sobre Firebase.

También puedes consultar el repositorio de GitHub del SDK de Firebase JavaScript para obtener una lista actualizada de los problemas informados y la solución de problemas, y enviar tus propios problemas allí.

Las construcciones del Admin SDK para Node.js no son compatibles con el SDK de Firebase JavaScript.

El Firebase Admin SDK para Node.js y el SDK de Firebase JavaScript son implementaciones distintas que no comparten definiciones de interfaz, clase ni función. Las instancias de objetos del Admin SDK no son compatibles con las funciones del SDK de Firebase JavaScript.

Por ejemplo, una instancia de FirebaseApp de Admin SDK que se pasa a la función getDatabase del SDK de Firebase JavaScript produce el siguiente error:

TypeError: Cannot read properties of undefined (reading 'getProvider')
 at _getProvider
 at getDatabase

Esto es cierto para toda la plataforma de la API del SDK de Firebase JavaScript, no solo para Realtime Database. Esto también se aplica al uso en la dirección opuesta. Si intentas usar el tipo Timestamp del SDK de JS de Cloud Firestore con Firebase Admin SDK para Node.js, se producen errores similares.

Evita usar versiones en conflicto del SDK de Firebase JavaScript

Si hay varias versiones en conflicto del SDK de Firebase JavaScript configuradas como dependencias en un proyecto, se generarán errores de entorno de ejecución cuando se pasen instancias de SDK entre paquetes de SDK. Por ejemplo, usar la biblioteca Data Connect con una versión de FirebaseApp que no coincide provoca el siguiente error:

Error: Component data-connect has not been registered yet

Por lo general, este problema se debe a una actualización de dependencias de uno, pero no de todos los paquetes del SDK de Firebase. Esta situación suele ocurrir cuando una herramienta de actualización de dependencias automatizada cambia un subconjunto de las dependencias del SDK de Firebase dentro del archivo yarn.lock o package-lock.json del proyecto. Dado que muchos SDK de Firebase JavaScript interoperan entre sí, el uso de varias versiones de los SDK causa incompatibilidades de entorno de ejecución.

Para solucionar este problema, borra el directorio node_modules/ y yarn.lock (para yarn) o package-lock.json (para npm) en tu proyecto y reinstala las dependencias.

Si los errores persisten, depura el problema con el comando npm ls. De esta manera, se registrarán las dependencias de tu proyecto para que puedas identificar las versiones en conflicto del módulo firebase.

Por ejemplo, en el siguiente registro, se muestra que package-using-older-firebase importa una versión en conflicto del SDK de 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

También pueden ocurrir errores debido a la combinación de las sentencias require y import de CJS y ESM en tu app. Esto crea varias instancias del SDK de Firebase JavaScript, cada una distinta de la otra, lo que inhabilita la interoperabilidad del SDK de Firebase JavaScript. Aumenta la verbosidad del agrupador que elijas para depurar esta situación. Por ejemplo, puedes usar la marca de análisis de esbuild para este fin.

Asegúrate de que los service workers estén empaquetados

Los service workers a menudo se compilan desde una canalización independiente del resto de una app web y no se incluyen en la configuración predeterminada de los agrupadores, como Webpack.

Si usas la versión modular del SDK de Firebase JavaScript en tu service worker, asegúrate de configurar el agrupador de apps para que incluya el archivo fuente del service worker. En el siguiente ejemplo, se usa npx para agrupar el service worker firebase-sw.js en el directorio src del proyecto:

npx esbuild ./src/firebase-sw.js --bundle --minify --main-fields=webworker,browser,module,main,default --outfile=public/firebase-sw.js

La activación de un service worker que no está agrupado fallará si importa módulos de ES que no admiten service workers o archivos que no existen en su alcance. A veces, estas fallas son silenciosas y difíciles de depurar.

Consulta Usa agrupadores de módulos con Firebase para obtener más información sobre cómo agrupar la versión modular del SDK de Firebase JavaScript en tu app.

Como alternativa, puedes eliminar la necesidad de agrupar importando los paquetes compat del SDK de Firebase JavaScript desde la 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();

Usa FirebaseServerApp cuando trabajes con la renderización del servidor

El SDK de Firebase JavaScript se diseñó originalmente para ejecutarse en entornos de navegador. La introducción de frameworks de renderización del servidor (SSR) lleva el uso del SDK a nuevos entornos de ejecución. Estos entornos de ejecución proporcionan un subconjunto de herramientas y APIs que proporcionan los navegadores web.

Por ejemplo, algunos SDK de Firebase requieren el almacenamiento en caché de datos con IndexedDB, una API solo para navegadores. Es posible que Firebase Auth requiera una interacción del usuario en ciertos flujos de acceso que es imposible en entornos de servidores sin interfaz gráfica. App Check se basa en heurísticas de navegador para validar al usuario antes de crear tokens de App Check.

Cuando trabajes con el SDK en estos nuevos entornos, usa FirebaseServerApp, una variante nueva de FirebaseApp que proporciona los medios para precargar la instancia de Firebase de SSR con los datos que se recopilaron del cliente.

FirebaseServerApp admite dos parámetros:

  • Token de ID de autenticación: Si se proporciona, Firebase Auth hace acceder automáticamente a un usuario autenticado antes, lo que podría abarcar una sesión en la división entre CSR y SSR.
  • Token de Verificación de aplicaciones: Si se proporciona, los otros SDK de Firebase lo usarán sin necesidad de inicializar una instancia de un cliente de App Check (que no se admite fuera de los entornos de navegador). Esto desbloquea la compatibilidad con SSR para los productos que tienen habilitada la App Check, como Cloud Functions, Data Connect, Cloud Firestore, Realtime Database y Vertex AI.

Consulta Optimiza el desarrollo de apps de SSR con FirebaseServerApp para ver un ejemplo de uso de FirebaseServerApp en Next.js.