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 ter acesso a uma lista atualizada dos problemas informados e respectivas soluções.
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 JavaScript Firebase 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 vai registrar 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 essa finalidade.
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
service worker 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.