Actualice de la versión 8 al SDK web modular

Las aplicaciones que actualmente usan Firebase Web SDK versión 8 o anterior deberían considerar migrar a la versión 9 siguiendo las instrucciones de esta guía.

Esta guía asume que está familiarizado con la versión 8 y que aprovechará un paquete de módulos como webpack o Rollup para actualizar y desarrollar la versión 9 en curso.

Se recomienda encarecidamente utilizar un paquete de módulos en su entorno de desarrollo. Si no usa uno, no podrá aprovechar los principales beneficios de la versión 9 en el tamaño reducido de la aplicación. Necesitará npm o yarn para instalar el SDK.

Los pasos de actualización de esta guía se basarán en una aplicación web imaginaria que usa los SDK de autenticación y Cloud Firestore. Al trabajar con los ejemplos, puede dominar los conceptos y los pasos prácticos necesarios para actualizar todos los SDK web de Firebase compatibles.

Acerca de las bibliotecas de compatibilidad

Hay dos tipos de bibliotecas disponibles para Firebase Web SDK versión 9:

  • Modular : una nueva superficie de API diseñada para facilitar el movimiento de árboles (eliminación de código no utilizado) para hacer que su aplicación web sea lo más pequeña y rápida posible.
  • Compat : una superficie API familiar que es totalmente compatible con la versión 8 SDK, lo que le permite actualizar a la versión 9 sin cambiar todo su código de Firebase a la vez. Las bibliotecas compatibles tienen pocas o ninguna ventaja de tamaño o rendimiento sobre sus contrapartes de la versión 8.

Esta guía asume que aprovechará las bibliotecas de compatibilidad de la versión 9 para facilitar su actualización. Estas bibliotecas le permiten continuar usando el código de la versión 8 junto con el código refactorizado para la versión 9. Esto significa que puede compilar y depurar su aplicación más fácilmente a medida que avanza en el proceso de actualización.

Para aplicaciones con una exposición muy pequeña al SDK web de Firebase, por ejemplo, una aplicación que solo realiza una simple llamada a las API de autenticación, puede ser práctico refactorizar el código de la versión 8 sin usar las bibliotecas de compatibilidad de la versión 9. Si está actualizando una aplicación de este tipo, puede seguir las instrucciones de esta guía para la "versión 9 modular" sin usar las bibliotecas de compatibilidad.

Sobre el proceso de actualización

Cada paso del proceso de actualización tiene un alcance para que pueda terminar de editar el código fuente de su aplicación y luego compilarlo y ejecutarlo sin interrupciones. En resumen, esto es lo que debe hacer para actualizar una aplicación:

  1. Agregue las bibliotecas de la versión 9 y las bibliotecas compatibles a su aplicación.
  2. Actualice las declaraciones de importación en su código a la compatibilidad con v9.
  3. Refactorice el código para un solo producto (por ejemplo, Autenticación) al estilo modular.
  4. Opcional: en este punto, elimine la biblioteca de compatibilidad de autenticación y el código de compatibilidad para la autenticación para obtener el beneficio del tamaño de la aplicación para la autenticación antes de continuar.
  5. Refactorice funciones para cada producto (por ejemplo, Cloud Firestore, FCM, etc.) al estilo modular, compilando y probando hasta que todas las áreas estén completas.
  6. Actualice el código de inicialización al estilo modular.
  7. Elimine todas las declaraciones de compatibilidad de la versión 9 restantes y el código de compatibilidad de su aplicación.

Obtenga la versión 9 del SDK

Para comenzar, obtenga las bibliotecas de la versión 9 y las bibliotecas compatibles usando npm:

npm i firebase@9.8.4

# OR

yarn add firebase@9.8.4

Actualizar las importaciones a la compatibilidad con v9

Para mantener su código funcionando después de actualizar su dependencia de v8 a v9 beta, cambie sus declaraciones de importación para usar la versión "compatible" de cada importación. Por ejemplo:

Antes: versión 8

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

Después: compatibilidad con la versión 9

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

Refactorizar al estilo modular

Si bien las API de la versión 8 se basan en un espacio de nombres y un patrón de servicio encadenados, el enfoque modular de la versión 9 significa que su código se organizará principalmente en torno a funciones . En la versión 9, el paquete firebase/app y otros paquetes no devuelven una exportación completa que contenga todos los métodos del paquete. En cambio, los paquetes exportan funciones individuales.

En la versión 9, los servicios se pasan como el primer argumento y la función luego usa los detalles del servicio para hacer el resto. Examinemos cómo funciona esto en dos ejemplos que refactorizan las llamadas a las API de autenticación y Cloud Firestore.

Ejemplo 1: refactorización de una función de autenticación

Antes: compatibilidad con la versión 9

El código de compatibilidad de la versión 9 es idéntico al código de la versión 8, pero las importaciones han cambiado.

import firebase from "firebase/compat/app";
import "firebase/compat/auth";

const auth = firebase.auth();
auth.onAuthStateChanged(user => { 
  // Check for user status
});

Después: versión 9 modular

La función getAuth toma firebaseApp como su primer parámetro. La función onAuthStateChanged no está encadenada desde la instancia de auth como lo estaría en la versión 8; en cambio, es una función gratuita que toma la auth como su primer parámetro.

import { getAuth, onAuthStateChanged } from "firebase/auth";

const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
  // Check for user status
});

Ejemplo 2: refactorización de una función de Cloud Firestore

Antes: compatibilidad con la versión 9

import "firebase/compat/firestore"

const db = firebase.firestore();
db.collection("cities").where("capital", "==", true)
    .get()
    .then((querySnapshot) => {
        querySnapshot.forEach((doc) => {
            // doc.data() is never undefined for query doc snapshots
            console.log(doc.id, " => ", doc.data());
        });
    })
    .catch((error) => {
        console.log("Error getting documents: ", error);
    });

Después: versión 9 modular

La función getFirestore toma firebaseApp como su primer parámetro, que se devolvió desde initializeApp en un ejemplo anterior. Tenga en cuenta cómo el código para formar una consulta es muy diferente en la versión 9; no hay encadenamiento y métodos como query o where ahora se exponen como funciones gratuitas.

import { getFirestore, collection, query, where, getDocs } from "firebase/firestore";

const db = getFirestore(firebaseApp);

const q = query(collection(db, "cities"), where("capital", "==", true));

const querySnapshot = await getDocs(q);
querySnapshot.forEach((doc) => {
  // doc.data() is never undefined for query doc snapshots
  console.log(doc.id, " => ", doc.data());
});

Actualice las referencias a Firestore DocumentSnapshot.exists

La versión 9 introduce un cambio importante en el que la propiedad firestore.DocumentSnapshot.exists se ha cambiado a un método . La funcionalidad es esencialmente la misma (probar si existe un documento), pero debe refactorizar su código para usar el método v9 como se muestra:

Antes: compatibilidad con la versión 9

if (snapshot.exists) {
  console.log("the document exists");
}

Después: versión 9 modular

if (snapshot.exists()) {
  console.log("the document exists");
}

Ejemplo 3: combinación de estilos de código de la versión 8 y la versión 9

El uso de las bibliotecas de compatibilidad durante la actualización le permite continuar usando el código de la versión 8 junto con el código refactorizado para la versión 9. Esto significa que puede mantener el código de la versión 8 existente para Cloud Firestore mientras refactoriza la autenticación u otro código SDK de Firebase al estilo de la versión 9, y aún compila con éxito tu aplicación con ambos estilos de código. Lo mismo ocurre con el código de la versión 8 y la versión 9 dentro de un producto como Cloud Firestore; Los estilos de código nuevos y antiguos pueden coexistir, siempre que importe los paquetes de compatibilidad:

import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'

const docRef = firebase.firestore().doc();
getDoc(docRef);

Tenga en cuenta que, aunque su aplicación se compilará, no obtendrá los beneficios de tamaño de aplicación del código modular hasta que elimine por completo las instrucciones y el código de compatibilidad de su aplicación.

Actualizar código de inicialización

Actualice el código de inicialización de su aplicación para usar la nueva sintaxis de la versión modular 9. Es importante actualizar este código después de haber completado la refactorización de todo el código en su aplicación; esto se debe a que firebase.initializeApp() inicializa el estado global para las API modulares y compatibles, mientras que la función initializeApp() modular inicializa solo el estado para modular.

Antes: compatibilidad con la versión 9

import firebase from "firebase/compat/app"

firebase.initializeApp({ /* config */ });

Después: versión 9 modular

import { initializeApp } from "firebase/app"

const firebaseApp = initializeApp({ /* config */ });

Eliminar código de compatibilidad

Para obtener los beneficios de tamaño del SDK modular de la versión 9, eventualmente debe convertir todas las invocaciones al estilo modular que se muestra arriba y eliminar todas las instrucciones de import "firebase/compat/* de su código. Cuando haya terminado, no debería haber más referencias al espacio de nombres global firebase.* o cualquier otro código en el estilo SDK de la versión 8.

Usando la biblioteca de compatibilidad desde la ventana

El SDK de la versión 9 está optimizado para trabajar con módulos en lugar del objeto de window del navegador. Las versiones anteriores de la biblioteca permitían la carga y administración de Firebase mediante el uso del espacio de nombres window.firebase . Esto no se recomienda en el futuro, ya que no permite la eliminación de código no utilizado. Sin embargo, la versión compatible del SDK de JavaScript funciona con la window para los desarrolladores que prefieren no comenzar de inmediato la ruta de actualización modular.

<script src="https://www.gstatic.com/firebasejs/9.8.4/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.8.4/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.8.4/firebase-auth-compat.js"></script>
<script>
   const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
   const db = firebaseApp.firestore();
   const auth = firebaseApp.auth();
</script>

La biblioteca de compatibilidad utiliza el código modular de la versión 9 debajo del capó y le proporciona la misma API que la versión 8 SDK; esto significa que puede consultar la referencia de la API de la versión 8 y los fragmentos de código de la versión 8 para obtener más detalles. Este método no se recomienda para uso a largo plazo, sino como un comienzo para actualizar a la biblioteca de la versión 9 totalmente modular.

Beneficios y limitaciones de la versión 9

La versión 9 completamente modularizada tiene estas ventajas sobre las versiones anteriores:

  • La versión 9 permite un tamaño de aplicación drásticamente reducido. Adopta el formato moderno del módulo de JavaScript, lo que permite prácticas de "movimiento de árboles" en las que importa solo los artefactos que necesita su aplicación. Dependiendo de su aplicación, la sacudida de árboles con la versión 9 puede resultar en un 80 % menos de kilobytes que una aplicación comparable creada con la versión 8.
  • La versión 9 continuará beneficiándose del desarrollo continuo de funciones, mientras que la versión 8 se congelará en un momento en el futuro.