Cómo usar la extensión Firestore Bundle Builder

La extensión Firestore Bundle Builder (firestore-bundle-builder) implementa una función de HTTP que entrega paquetes de datos de Cloud Firestore. Defines los paquetes en documentos de Firestore, y la extensión entrega paquetes de datos con archivos binarios estáticos a través de solicitudes HTTP, junto con varios mecanismos de almacenamiento en caché mediante la CDN Firebase Hosting o Cloud Storage. Cuando no hay un paquete o los paquetes existentes hayan vencido, esta función creará y almacenará en caché un paquete nuevo a pedido.

Para usar esta extensión, primero debes crear una o más especificaciones de paquetes en Firestore con el panel de administración de la extensión. La especificación del paquete es la forma en la que defines las consultas con nombre (consultas de colección y rutas de documentos específicas para agregar al paquete).

Dentro de las especificaciones del paquete, también puedes definir los parámetros que se usarán en las consultas con nombre. Estableces valores para estos parámetros mediante los parámetros de consulta de URL cuando llamas a la función de HTTP.

El vínculo anterior proporciona algunas instrucciones para que puedas ejecutar las utilidades de administración de forma local. Una vez que configures la app web, navega a localhost:3000 para crear una especificación con la IU:

Cómo compilar y entregar el paquete

Una vez que instales la extensión y crees una especificación de paquete, podrás comenzar a compilar y entregar paquetes llamando al extremo HTTP proporcionado por la extensión.

Según la especificación, es posible que el paquete solicitado se muestre desde la caché del cliente, desde la caché de Firebase Hosting o desde un archivo de Cloud Storage. Cuando venzan todas las memorias caché, una nueva solicitud de entrega activará las consultas de Firestore para compilar el paquete a pedido.

Puedes aprovechar las funciones de la CDN de Firebase Hosting si configuras un sitio de Firebase Hosting que apunte a la función de entrega con una regla de reescritura. Las CDN replican tu paquete en muchos servidores diferentes para que los usuarios puedan cargarlo automáticamente desde el servidor más cercano. Este es el enfoque que se prefiere.

Para configurar esto en Firebase Hosting, crea o edita un archivo firebase.json con el contenido a continuación y, luego, implementa el siguiente sitio:

{
  "hosting": {
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
    "rewrites": [
      {
        "source": "/bundles/*",
        "function": "ext-firestore-bundle-builder-serve"
      }
    ]
  }
}

Una vez implementado, puedes acceder a tus paquetes desde la CDN con la URL del sitio. Por ejemplo: https://your-site-url.com/bundles/:bundleId.

También puedes configurar la extensión para que almacene datos en caché en Cloud Storage si no quieres usar Firebase Hosting. En este caso, llamarías directamente a la función de HTTP implementada para generar paquetes.

Integración de clientes

A continuación, puedes consumir un paquete con la API de loadBundle de los SDK de Cloud Firestore. Primero debes descargar el paquete y, luego, proporcionarlo al SDK. Por ejemplo:

import { loadBundle } from "firebase/firestore";

// Download the bundle from the Firebase Hosting CDN:
const bundle = await fetch("/bundles/:bundleId");

// If not using a CDN, download the bundle directly:
// const bundle = await fetch('https://<location>-<project-id>.cloudfunctions.net/ext-firestore-bundle-builder-serve/:bundleId');

await loadBundle(bundle);

Una vez cargados, puedes usar los datos del paquete:

Si especificaste un array de las rutas de acceso de los documentos cuando definiste el paquete, puedes obtener los datos del documento en el cliente a través del paquete:

import { getFirestore, doc, getDocFromCache } from "firebase/firestore";
// Bundle Document IDs: ['users/92x1NgSWYKUC4AG4s2nHGMR2ikZ2']

const ref = doc(getFirestore(), "users/92x1NgSWYKUC4AG4s2nHGMR2ikZ2");
const snapshot = await getDocFromCache(ref);

Si especificaste búsquedas, puedes usar la API de namedQuery para ejecutar una consulta desde el paquete:

import { getFirestore, namedQuery } from "firebase/firestore";
const query = await namedQuery(getFirestore(), "queryId");
const snapshot = await getDocsFromCache(query);

Los IDs de consulta se definen como una clave de cada definición de la propiedad queries (consulta a continuación).