Como usar a extensão Firestore Bundle Builder

A extensão Firestore Bundle Builder (firestore-bundle-builder) implanta uma função HTTP que disponibiliza pacotes de dados do Cloud Firestore. Defina os pacotes nos documentos do Firestore para a extensão disponibilizar o pacote de dados de arquivos binários estáticos via solicitações HTTP, bem como vários mecanismos de armazenamento em cache integrados usando a CDN do Firebase Hosting ou o Cloud Storage. Quando nenhum pacote existir ou os pacotes atuais expirarem, essa função criará e armazenará em cache um novo pacote sob demanda.

Para usar essa extensão, primeiro você precisa criar uma ou mais especificações de pacote no Firestore usando o painel de administração da extensão. As consultas nomeadas são definidas ao especificar o pacote (consultas de coleção e caminhos de documentos específicos a serem adicionados ao pacote).

Dentro da especificação do pacote, também é possível definir parâmetros que precisem ser usados em consultas nomeadas. Defina valores para esses parâmetros usando parâmetros de consulta de URL ao chamar a função HTTP.

O link acima fornece algumas instruções para você executar os utilitários do administrador localmente. Depois de configurar o app da Web, acesse localhost:3000 para criar uma especificação usando a IU:

Como criar e disponibilizar o pacote

Depois de instalar a extensão e criar uma especificação de pacote, é possível começar a criar e disponibilizar pacotes chamando o endpoint HTTP fornecido pela extensão.

Dependendo da especificação, o pacote solicitado pode ser retornado do cache do cliente, do cache do Firebase Hosting ou de um arquivo do Cloud Storage. Quando todos os caches expirarem, uma nova solicitação de disponibilização acionará consultas do Firestore para criar o pacote sob demanda.

Para aproveitar os recursos da CDN do Firebase Hosting, use uma regra de substituição para configurar um site do Firebase Hosting que aponte para a função de disponibilização. As CDNs replicam o pacote em vários servidores para que os usuários possam carregar o pacote do servidor mais próximo automaticamente. Essa é a abordagem mais usada.

Para configurar isso no Firebase Hosting, crie ou edite um arquivo firebase.json com o conteúdo a seguir e implante o site:

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

Após a implantação, será possível acessar os pacotes pela CDN usando o URL do site. Por exemplo, https://your-site-url.com/bundles/:bundleId.

Se não quiser usar o Firebase Hosting, configure a extensão para armazenar em cache os dados no Cloud Storage. Nesse caso, você chamaria a função HTTP implantada diretamente para gerar pacotes.

Integração do cliente

Em seguida, é possível consumir um pacote com a API loadBundle dos SDKs do Cloud Firestore. Primeiro, é preciso fazer o download do pacote e, depois, enviá-lo ao SDK. Exemplo:

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);

Após o carregamento, é possível usar os dados do pacote das seguintes maneiras:

Se você tiver especificado uma matriz de caminhos de documentos quando definiu o pacote, poderá receber os dados do documento no cliente usando o pacote:

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

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

Se você tiver especificado as consultas, use a API namedQuery para executar uma consulta a partir do pacote:

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

Os IDs de consulta são definidos como uma chave de cada definição de propriedade queries (veja abaixo).