Le app che attualmente utilizzano Firebase Web SDK versione 8 o precedenti dovrebbero prendere in considerazione la migrazione alla versione 9 utilizzando le istruzioni in questa guida.
Questa guida presuppone che tu abbia familiarità con la versione 8 e che trarrai vantaggio da un bundle di moduli come webpack o Rollup per l'aggiornamento e lo sviluppo continuo della versione 9.
Si consiglia vivamente di utilizzare un bundler di moduli nel proprio ambiente di sviluppo. Se non ne utilizzi uno, non sarai in grado di sfruttare i principali vantaggi della versione 9 in termini di dimensioni ridotte dell'app. Avrai bisogno di npm o yarn per installare l'SDK.
I passaggi di aggiornamento in questa guida si baseranno su un'app Web immaginaria che utilizza l'autenticazione e gli SDK di Cloud Firestore. Utilizzando gli esempi, puoi padroneggiare i concetti e i passaggi pratici necessari per aggiornare tutti gli SDK Web Firebase supportati.
Informazioni sulle librerie compat
Sono disponibili due tipi di librerie per Firebase Web SDK versione 9:
- Modulare : una nuova superficie API progettata per facilitare lo scuotimento dell'albero (rimozione del codice inutilizzato) per rendere la tua app Web il più piccola e veloce possibile.
- Compat : una superficie API familiare che è completamente compatibile con l'SDK versione 8, consentendoti di eseguire l'aggiornamento alla versione 9 senza modificare tutto il codice Firebase in una volta. Le librerie Compat hanno pochi o nessun vantaggio in termini di dimensioni o prestazioni rispetto alle loro controparti della versione 8.
Questa guida presuppone che trarrai vantaggio dalle librerie compat della versione 9 per facilitare il tuo aggiornamento. Queste librerie ti consentono di continuare a utilizzare il codice della versione 8 insieme al codice rifattorizzato per la versione 9. Ciò significa che puoi compilare ed eseguire il debug dell'app più facilmente mentre esegui il processo di aggiornamento.
Per le app con un'esposizione molto ridotta all'SDK Web Firebase, ad esempio un'app che effettua solo una semplice chiamata alle API di autenticazione, può essere pratico eseguire il refactoring del codice della versione 8 senza utilizzare le librerie di compatibilità della versione 9. Se stai aggiornando un'app di questo tipo, puoi seguire le istruzioni in questa guida per la "versione 9 modulare" senza utilizzare le librerie compat.
Informazioni sul processo di aggiornamento
Ogni passaggio del processo di aggiornamento ha l'ambito in modo che tu possa completare la modifica dell'origine per la tua app, quindi compilarla ed eseguirla senza interruzioni. In sintesi, ecco cosa farai per aggiornare un'app:
- Aggiungi le librerie della versione 9 e le librerie di compatibilità alla tua app.
- Aggiorna le istruzioni di importazione nel tuo codice alla compatibilità v9.
- Codice di refactoring per un singolo prodotto (ad esempio, Autenticazione) allo stile modulare.
- Facoltativo: a questo punto, rimuovere la libreria di compatibilità di autenticazione e il codice di compatibilità per l'autenticazione per realizzare il vantaggio della dimensione dell'app per l'autenticazione prima di continuare.
- Funzioni di refactor per ogni prodotto (ad esempio Cloud Firestore, FCM, ecc.) allo stile modulare, compilazione e test fino al completamento di tutte le aree.
- Aggiorna il codice di inizializzazione allo stile modulare.
- Rimuovi tutte le restanti istruzioni di compatibilità della versione 9 e il codice di compatibilità dalla tua app.
Ottieni l'SDK versione 9
Per iniziare, ottieni le librerie della versione 9 e le librerie di compatibilità usando npm:
npm i firebase@9.18.0 # OR yarn add firebase@9.18.0
Aggiorna le importazioni alla compatibilità v9
Per mantenere il codice funzionante dopo aver aggiornato la dipendenza da v8 a v9 beta, modifica le istruzioni di importazione per utilizzare la versione "compatibile" di ogni importazione. Per esempio:
Prima: versione 8
import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';
Dopo: versione 9 compat
// v9 compat packages are API compatible with v8 code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';
Refactor allo stile modulare
Sebbene le API della versione 8 siano basate su uno spazio dei nomi a catena di punti e su un modello di servizio, l'approccio modulare della versione 9 significa che il codice sarà organizzato principalmente attorno alle funzioni . Nella versione 9, il pacchetto firebase/app e altri pacchetti non restituiscono un'esportazione completa che contiene tutti i metodi del pacchetto. Invece, i pacchetti esportano singole funzioni.
Nella versione 9, i servizi vengono passati come primo argomento e la funzione utilizza quindi i dettagli del servizio per fare il resto. Esaminiamo come funziona in due esempi che effettuano il refactoring delle chiamate alle API di autenticazione e di Cloud Firestore.
Esempio 1: refactoring di una funzione di autenticazione
Prima: versione 9 compat
Il codice di compatibilità della versione 9 è identico al codice della versione 8, ma le importazioni sono cambiate.
import firebase from "firebase/compat/app";
import "firebase/compat/auth";
const auth = firebase.auth();
auth.onAuthStateChanged(user => {
// Check for user status
});
Dopo: versione 9 modulare
La funzione getAuth prende firebaseApp come primo parametro. La funzione onAuthStateChanged non è concatenata dall'istanza di auth come sarebbe nella versione 8; invece, è una funzione libera che prende auth come primo parametro.
import { getAuth, onAuthStateChanged } from "firebase/auth";
const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
// Check for user status
});
Gestione degli aggiornamenti del metodo Auth getRedirectResult
La versione 9 introduce una modifica di rilievo in getRedirectResult . Quando non viene chiamata alcuna operazione di reindirizzamento, la versione 9 restituisce null rispetto alla versione 8, che ha restituito una UserCredential con un utente null .
Prima: versione 9 compat
const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
return null;
}
return result;
Dopo: versione 9 modulare
const result = await getRedirectResult(auth);
// Provider of the access token could be Facebook, Github, etc.
if (result === null || provider.credentialFromResult(result) === null) {
return null;
}
return result;
Esempio 2: refactoring di una funzione Cloud Firestore
Prima: versione 9 compat
import "firebase/compat/firestore"
const db = firebase.firestore();
db.collection("cities").where("capital", "==", true)
.get()
.then((querySnapshot) => {
querySnapshot.forEach((doc) => {
// doc.data() is never undefined for query doc snapshots
console.log(doc.id, " => ", doc.data());
});
})
.catch((error) => {
console.log("Error getting documents: ", error);
});
Dopo: versione 9 modulare
La funzione getFirestore accetta firebaseApp come primo parametro, restituito da initializeApp in un esempio precedente. Nota come il codice per formare una query è molto diverso nella versione 9; non c'è concatenamento e metodi come query o where sono ora esposti come funzioni libere.
import { getFirestore, collection, query, where, getDocs } from "firebase/firestore";
const db = getFirestore(firebaseApp);
const q = query(collection(db, "cities"), where("capital", "==", true));
const querySnapshot = await getDocs(q);
querySnapshot.forEach((doc) => {
// doc.data() is never undefined for query doc snapshots
console.log(doc.id, " => ", doc.data());
});
Aggiorna i riferimenti a Firestore DocumentSnapshot.exists
La versione 9 introduce una modifica sostanziale in cui la proprietà firestore.DocumentSnapshot.exists è stata modificata in un metodo . La funzionalità è essenzialmente la stessa (testare se esiste un documento) ma è necessario refactoring del codice per utilizzare il metodo v9 come mostrato:
Prima: versione 9 compat
if (snapshot.exists) {
console.log("the document exists");
}
Dopo: versione 9 modulare
if (snapshot.exists()) {
console.log("the document exists");
}
Esempio 3: combinazione di stili di codice versione 8 e versione 9
L'utilizzo delle librerie di compatibilità durante l'aggiornamento ti consente di continuare a utilizzare il codice della versione 8 insieme al codice rifattorizzato per la versione 9. Ciò significa che puoi mantenere il codice della versione 8 esistente per Cloud Firestore mentre esegui il refactoring dell'autenticazione o di altro codice Firebase SDK allo stile della versione 9, e comunque compila correttamente la tua app con entrambi gli stili di codice. Lo stesso vale per il codice della versione 8 e della versione 9 all'interno di un prodotto come Cloud Firestore; nuovi e vecchi stili di codice possono coesistere, purché si importino i pacchetti compat:
import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'
const docRef = firebase.firestore().doc();
getDoc(docRef);
Tieni presente che, sebbene la tua app venga compilata, non otterrai i vantaggi delle dimensioni dell'app del codice modulare fino a quando non rimuoverai completamente le istruzioni di compatibilità e il codice dalla tua app.
Aggiorna il codice di inizializzazione
Aggiorna il codice di inizializzazione dell'app per utilizzare la nuova sintassi modulare della versione 9. È importante aggiornare questo codice dopo aver completato il refactoring di tutto il codice nell'app; questo perché firebase.initializeApp() inizializza lo stato globale sia per le API compat che modular, mentre la funzione modular initializeApp() inizializza solo lo stato per modular.
Prima: versione 9 compat
import firebase from "firebase/compat/app"
firebase.initializeApp({ /* config */ });
Dopo: versione 9 modulare
import { initializeApp } from "firebase/app"
const firebaseApp = initializeApp({ /* config */ });
Rimuovi il codice di compatibilità
Per realizzare i vantaggi in termini di dimensioni dell'SDK modulare versione 9, dovresti eventualmente convertire tutte le invocazioni nello stile modulare mostrato sopra e rimuovere tutte le istruzioni di import "firebase/compat/* dal tuo codice. Quando hai finito, non dovrebbero esserci più riferimenti allo spazio dei nomi globale di firebase.* o qualsiasi altro codice nello stile dell'SDK della versione 8.
Utilizzando la libreria di compatibilità dalla finestra
L'SDK versione 9 è ottimizzato per funzionare con i moduli anziché con l'oggetto window del browser. Le versioni precedenti della libreria consentivano il caricamento e la gestione di Firebase utilizzando lo spazio dei nomi window.firebase . Questo non è raccomandato in futuro in quanto non consente l'eliminazione del codice inutilizzato. Tuttavia, la versione compatibile di JavaScript SDK funziona con la window per gli sviluppatori che preferiscono non iniziare immediatamente il percorso di aggiornamento modulare.
<script src="https://www.gstatic.com/firebasejs/9.18.0/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.18.0/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.18.0/firebase-auth-compat.js"></script>
<script>
const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
const db = firebaseApp.firestore();
const auth = firebaseApp.auth();
</script>
La libreria di compatibilità utilizza il codice modulare della versione 9 sotto il cofano e lo fornisce con la stessa API dell'SDK della versione 8; ciò significa che puoi fare riferimento al riferimento API della versione 8 e ai frammenti di codice della versione 8 per i dettagli. Questo metodo non è consigliato per un uso a lungo termine, ma come inizio per l'aggiornamento alla libreria versione 9 completamente modulare.
Vantaggi e limitazioni della versione 9
La versione 9 completamente modularizzata presenta questi vantaggi rispetto alle versioni precedenti:
- La versione 9 consente una dimensione dell'app notevolmente ridotta. Adotta il moderno formato del modulo JavaScript, consentendo pratiche di "scuotimento degli alberi" in cui importi solo gli artefatti necessari alla tua app. A seconda dell'app, lo scuotimento degli alberi con la versione 9 può comportare l'80% di kilobyte in meno rispetto a un'app comparabile creata con la versione 8.
- La versione 9 continuerà a beneficiare del continuo sviluppo delle funzionalità, mentre la versione 8 verrà bloccata in futuro.