Práticas recomendadas do SDK do Firebase para JavaScript

Esta página oferece dicas e soluções de problemas de JavaScript que você pode encontrar ao usar o SDK Firebase JavaScript.

Você está enfrentando algum outro desafio ou seu problema não está descrito abaixo? Confira as Perguntas frequentes sobre o Firebase para ver mais dúvidas relacionadas ao Firebase ou a um produto específico.

Confira também o repositório do GitHub do SDK Firebase JavaScript para consultar uma lista atualizada de problemas informados e soluções de problemas e enviar seus próprios problemas.

Admin SDK para construções do Node.js não são compatíveis com o SDK JavaScript do Firebase

O Firebase Admin SDK para Node.js e o SDK Firebase JavaScript são implementações distintas que não compartilham definições de interface, classe ou função. As instâncias de objetos Admin SDK são incompatíveis com as funções do SDK Firebase JavaScript.

Por exemplo, uma instância do FirebaseApp do Admin SDK transmitida para a função getDatabase do SDK Firebase JavaScript produz o seguinte erro:

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

Isso é válido para toda a superfície da API SDK Firebase JavaScript, não apenas para Realtime Database. Isso também é verdadeiro para o uso na direção oposta. Tentar usar o tipo Timestamp do SDK JS Cloud Firestore com o Firebase Admin SDK para Node.js produz erros semelhantes.

Evite usar versões conflitantes do SDK JavaScript do Firebase

Várias versões conflitantes do SDK JavaScript Firebase configuradas como dependências em um projeto vão causar erros de execução quando as instâncias do SDK forem transmitidas entre pacotes do SDK. Por exemplo, o uso da biblioteca Data Connect com uma versão incompatível de FirebaseApp causa o seguinte erro:

Error: Component data-connect has not been registered yet

Esse problema geralmente é causado por uma atualização de dependência de um dos pacotes do SDK do Firebase, mas não de todos. Essa situação geralmente ocorre quando uma ferramenta de atualização de dependências automatizada muda um subconjunto das dependências do SDK do Firebase no arquivo yarn.lock ou package-lock.json do projeto. Como muitos SDKs JavaScript do Firebase interagem entre si, o uso de várias versões dos SDKs causa incompatibilidades no tempo de execução.

Para corrigir esse problema, exclua o diretório node_modules/ e o yarn.lock (para yarn) ou package-lock.json (para npm) no projeto e reinstale as dependências.

Se os erros persistirem, depure o problema com o comando npm ls. Isso registra as dependências do projeto para que você possa identificar versões conflitantes do módulo firebase.

Por exemplo, o registro a seguir mostra package-using-older-firebase importando uma versão em conflito do SDK JavaScript do Firebase:

$ 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

Erros também podem ocorrer devido à mistura de instruções require e import do CJS e do ESM no app. Isso cria várias instâncias do SDK Firebase JavaScript, cada uma distinta da outra, o que interrompe a interoperabilidade do SDK Firebase JavaScript. Aumente a verbosidade do bundler escolhido para depurar esse cenário. Por exemplo, é possível usar a flag esbuild analyze para esse fim.

Verifique se os service workers estão agrupados

Os workers de serviço geralmente são criados em um pipeline separado do restante de um app da Web e não são incluídos na configuração padrão de bundlers, como o Webpack.

Se você usar a versão modular do SDK JavaScript Firebase no worker de serviço, configure o bundler do app para incluir o arquivo de origem do worker de serviço. O exemplo a seguir usa npx para agrupar o worker de serviço firebase-sw.js no diretório src do projeto:

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

A ativação de um service worker que não está agrupado vai falhar se ele importar módulos ES que não oferecem suporte a service workers ou arquivos que não existem no escopo do service worker. Às vezes, essas falhas são silenciosas e difíceis de depurar.

Consulte Como usar os bundlers de módulos com o Firebase para mais informações sobre como agrupar a versão modular do SDK JavaScript do Firebase no seu app.

Como alternativa, você pode eliminar a necessidade de agrupamento importando os pacotes do SDK compat Firebase JavaScript do 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();

Use FirebaseServerApp ao trabalhar com a renderização do lado do servidor

O SDK JavaScript Firebase foi originalmente criado para ser executado em ambientes de navegador. A introdução de frameworks de renderização do lado do servidor (SSR, na sigla em inglês) impulsiona o uso do SDK em novos ambientes de execução. Esses ambientes de execução fornecem um subconjunto de ferramentas e APIs que os navegadores da Web oferecem.

Por exemplo, alguns SDKs do Firebase exigem armazenamento em cache de dados com IndexedDB, uma API exclusiva para navegadores. O Firebase Auth pode exigir a interação do usuário em determinados fluxos de login que são impossíveis em ambientes de servidor sem cabeça. O App Check depende de heurísticas do navegador para validar o usuário antes de criar tokens App Check.

Ao trabalhar com o SDK nesses novos ambientes, use FirebaseServerApp, uma nova variante de FirebaseApp que fornece o meio para pré-carregar a instância do Firebase SSR com dados coletados do lado do cliente.

FirebaseServerApp aceita dois parâmetros:

  • Auth ID Token: se fornecido, o Firebase Authentication faz login automaticamente em um usuário autenticado anteriormente, potencialmente abrangendo uma sessão em toda a divisão CSR / SSR.
  • Token do App Check: se fornecido, o token é usado pelos outros SDKs do Firebase sem a necessidade de inicializar uma instância de um cliente App Check, que não tem suporte fora dos ambientes do navegador. Isso desbloqueia o suporte ao SSR para produtos com App Check ativado, como Cloud Functions, Data Connect, Cloud Firestore, Realtime Database e Vertex AI.

Consulte Simplificar o desenvolvimento de apps SSR com o FirebaseServerApp para conferir um exemplo de uso de FirebaseServerApp no Next.js.