Best practice per l'SDK Firebase JavaScript

Questa pagina offre suggerimenti e soluzioni per i problemi di JavaScript che potresti riscontrare quando utilizzi l'SDK Firebase JavaScript.

Hai altri problemi o non vedi il tuo problema? Assicurati di consultare le domande frequenti principali su Firebase per altre domande frequenti generali o specifiche per prodotto.

Puoi anche consultare il Firebase JavaScript SDK GitHub repo per un elenco aggiornato dei problemi segnalati e della risoluzione dei problemi, nonché per segnalare i tuoi problemi.

I costrutti Admin SDK per Node.js non sono compatibili con l'SDK Firebase JavaScript

Firebase Admin SDK per Node.js e l'SDK Firebase JavaScript sono implementazioni distinte che non condividono definizioni di interfaccia, classe o funzione. Le istanze di oggetti Admin SDK non sono compatibili con le funzioni SDK Firebase JavaScript.

Ad esempio, un'istanza di FirebaseApp di Admin SDK passata alla funzione getDatabase dell'SDK Firebase JavaScript genera il seguente errore:

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

Questo vale per l'intera API SDK Firebase JavaScript, non solo per Realtime Database. Vale anche per l'utilizzo nella direzione opposta. Il tentativo di utilizzare il tipo Timestamp dell'SDK JS Cloud Firestore con Firebase Admin SDK per Node.js genera errori simili.

Evita di utilizzare versioni in conflitto dell'SDK Firebase JavaScript

Più versioni in conflitto dell'SDK Firebase JavaScript configurate come dipendenze in un progetto causeranno errori di runtime quando le istanze SDK vengono passate tra i pacchetti SDK. Ad esempio, l'utilizzo della libreria Data Connect con una versione di FirebaseApp non corrispondente causa il seguente errore:

Error: Component data-connect has not been registered yet

Questo problema è in genere causato da un aggiornamento delle dipendenze di uno, ma non di tutti, i pacchetti SDK Firebase. Questa situazione si verifica spesso quando uno strumento di aggiornamento automatico delle dipendenze modifica un sottoinsieme delle dipendenze dell'SDK Firebase all'interno del file yarn.lock o package-lock.json del progetto. Poiché molti SDK Firebase JavaScript interagiscono tra loro, l'utilizzo di varie versioni degli SDK causa incompatibilità di runtime.

Per risolvere il problema, elimina la directory node_modules/ e yarn.lock (per yarn) o package-lock.json (per npm) nel progetto e reinstalla le dipendenze.

Se gli errori persistono, esegui ulteriormente il debug del problema con il comando npm ls. Verranno registrate le dipendenze del progetto in modo da poter identificare le versioni in conflitto del modulo firebase.

Ad esempio, il seguente log mostra che package-using-older-firebase sta importando una versione in conflitto dell'SDK Firebase JavaScript:

$ 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

Gli errori possono verificarsi anche a causa della combinazione di istruzioni require e import di CJS ed ESM nella tua app. Ciò crea più istanze dell'SDK Firebase JavaScript, ciascuna distinta dall'altra, il che impedisce l'interoperabilità dell'SDK Firebase JavaScript. Aumenta la modalità dettagliata del tuo bundler preferito per eseguire il debug di questo scenario. Ad esempio, puoi utilizzare il flag di analisi esbuild per questo scopo.

Assicurati che i worker di servizio siano raggruppati

I service worker vengono spesso creati da una pipeline separata dal resto di un'app web e non sono inclusi nella configurazione predefinita di bundler come Webpack.

Se utilizzi la versione modulare dell'SDK Firebase JavaScript all'interno del tuo servizio worker, assicurati di configurare il bundler dell'app in modo da includere il file sorgente del servizio worker. L'esempio seguente utilizza npx per raggruppare il servizio worker firebase-sw.js nella directory src del progetto:

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

L'attivazione di un service worker non in bundle non andrà a buon fine se importa moduli ES che non supportano i service worker o file che non esistono nell'ambito del service worker. A volte questi errori sono silenziosi e difficili da eseguire il debug.

Per ulteriori informazioni sul bundling della versione modulare dell'SDK Firebase JavaScript nella tua app, consulta Utilizzare i bundler dei moduli con Firebase.

In alternativa, puoi eliminare la necessità di eseguire il bundling importando i bundle SDK compat Firebase JavaScript dalla 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();

Utilizza FirebaseServerApp quando lavori con il rendering lato server

L'SDK Firebase JavaScript era originariamente progettato per funzionare in ambienti browser. L'introduzione di framework di rendering lato server (SSR) spinge l'utilizzo dell'SDK in nuovi ambienti di runtime. Questi runtime forniscono un sottoinsieme di strumenti e API forniti dai browser web.

Ad esempio, alcuni SDK Firebase richiedono la memorizzazione nella cache dei dati con IndexedDB, un'API solo per browser. Firebase Auth potrebbe richiedere l'interazione dell'utente in determinati flussi di accesso che non sono possibili negli ambienti server headless. App Check si basa su metodi di euristica del browser per convalidare l'utente prima di creare i token App Check.

Quando utilizzi l'SDK in questi nuovi ambienti, utilizza FirebaseServerApp, una nuova variante di FirebaseApp che fornisce i mezzi per precaricare l'istanza Firebase SSR con i dati raccolti lato client.

FirebaseServerApp supporta due parametri:

  • Token ID autenticazione: se fornito, Firebase Auth fa accedere automaticamente un utente autenticato in precedenza, potenzialmente su una sessione che attraversa la divisione tra CSR e SSR.
  • Token App Check: se fornito, il token viene utilizzato dagli altri SDK Firebase senza dover inizializzare un'istanza di un client App Check (che non è supportato al di fuori degli ambienti browser). In questo modo viene sbloccato il supporto SSR per i prodotti in cui è attivato App Check, ad esempio Cloud Functions, Data Connect, Cloud Firestore, Realtime Database e Vertex AI.

Consulta Semplifica lo sviluppo di app SSR con FirebaseServerApp per esempi di utilizzo di FirebaseServerApp in Next.js.