Eseguire l'upgrade all'SDK web modulare (v9)

Le app che attualmente utilizzano la versione 8 o precedenti dell'SDK web dovrebbero valutare la possibilità di eseguire la migrazione alla versione 9 seguendo le istruzioni riportate in questa guida.

Questa guida presuppone che tu abbia dimestichezza con la versione 8 e che utilizzerai un bundler di moduli come webpack o Rollup per l'upgrade e lo sviluppo continuo della versione 9.

Ti consigliamo vivamente di utilizzare un aggregatore di moduli nell'ambiente di sviluppo. Se non ne utilizzi uno, non potrai usufruire dei vantaggi principali della versione 9, ovvero le dimensioni ridotte delle app. Per installare l'SDK, devi disporre di npm o yarn.

Informazioni sulle librerie compat

Per la versione 9 dell'SDK web sono disponibili due tipi di librerie:

  • Modulare: una nuova API progettata per semplificare l'eliminazione di codice non utilizzato (tree-shaking) per rendere la tua app web il più piccola e veloce possibile.
  • Compat: un'interfaccia API familiare completamente compatibile con la versione 8, che ti consente di eseguire l'upgrade alla versione 9 senza modificare tutto il codice dell'SDK contemporaneamente. Le librerie compatibili hanno vantaggi in termini di dimensioni o rendimento minimi o nulli rispetto alle controparti della versione 8.

Questa guida presuppone che tu utilizzi le librerie di compatibilità della versione 9 per semplificare l'upgrade. Queste librerie ti consentono di continuare a utilizzare il codice della versione 8 insieme al codice sottoposto a refactoring per la versione 9. Ciò significa che puoi compilare e eseguire il debug della tua app più facilmente durante la procedura di upgrade.

Per le app con un'esposizione molto ridotta all'SDK web, potrebbe essere pratico eseguire il refactoring del codice della versione 8 senza utilizzare le librerie di compatibilità della versione 9. Se stai eseguendo l'upgrade di un'app di questo tipo, puoi seguire le istruzioni riportate in questa guida per la "versione 9 modulare" senza utilizzare le librerie compat.

Informazioni sulla procedura di upgrade

Ogni passaggio della procedura di upgrade è definito in modo da poter completare la modifica del codice sorgente della tua app, quindi compilarla ed eseguirla senza interruzioni. In sintesi, Ecco cosa devi fare per eseguire l'upgrade di un'app:

  1. Aggiungi le librerie della versione 9 e le librerie compat alla tua app.
  2. Aggiorna le istruzioni di importazione nel codice alla compatibilità con la versione 9.
  3. Esegui il refactoring del codice in modo che sia modulare.
  4. Rimuovi la libreria di compatibilità e il codice di compatibilità per l'autenticazione per usufruire del vantaggio delle dimensioni dell'app.
  5. Aggiorna il codice di inizializzazione allo stile modulare.
  6. Rimuovi dalla tua app tutte le dichiarazioni di compatibilità e il codice di compatibilità rimanenti della versione 9.

Ottenere l'SDK versione 9

Per iniziare, scarica le librerie della versione 9 e le librerie compat utilizzando npm (versione più recente https://www.npmjs.com/package/firebase):

npm i firebase@11.0.2

# OR

yarn add firebase@11.0.2

Aggiornare le importazioni alla compatibilità con la versione 9

Per mantenere il codice funzionante dopo l'aggiornamento della dipendenza dalla versione 8 alla versione 9, modifica le istruzioni di importazione in modo da utilizzare la versione "compat" di ogni importazione. Ad esempio:

Prima: versione 8

import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';

Dopo: compatibile con la versione 9

// v9 compat packages are API compatible with v8 code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';

Esegui il refactoring in base allo stile modulare

Sebbene le API della versione 8 siano basate su un pattern di servizio e spazio dei nomi concatenato da punti, l'approccio modulare della versione 9 prevede che il codice sia organizzato principalmente in base alle functions. Nella versione 9, il pacchetto firebase/app e altri pacchetti non restituiscono un'esportazione completa che contenga tutti i metodi del pacchetto. I pacchetti, invece, esportano singole funzioni.

Nella versione 9, i servizi vengono passati come primo argomento e la funzione utilizza i dettagli del servizio per fare il resto.

Esempio: refactoring di una semplice funzione di autenticazione

Prima: compatibilità con la versione 9

Il codice di compatibilità della versione 9 è identico a quello della versione 8, ma le importazioni sono cambiate. L'utilizzo delle librerie compat durante l'upgrade ti consente di continuare a utilizzare il codice della versione 8 insieme al codice sottoposto a refactoring per la versione 9.

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 utilizza firebaseApp come primo parametro. La funzione onAuthStateChanged non è collegata all'istanza di autenticazione come nella versione 8, ma è 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
});

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 dell'app. Questo perché firebase.initializeApp() inizializza lo stato globale sia per le API compat che per quelle modulari, mentre la funzione initializeApp() modulare inizializza solo lo stato per le API modulari.

Prima: compatibilità con la versione 9

import firebase from "firebase/compat/app"

firebase.initializeApp({ /* config */ });

Dopo: versione 9 modulare

import { initializeApp } from "firebase/app"

const firebaseApp = initializeApp({ /* config */ });

Rimuovere il codice di compatibilità

Per usufruire dei vantaggi in termini di dimensioni dell'SDK modulare della versione 9, dovresti eventualmente convertire tutte le invocazioni allo stile modulare mostrato sopra e rimuovere tutte le affermazioni import "firebase/compat/* dal codice. Al termine, non devono essere presenti riferimenti allo spazio dei nomi globale firebase.* o ad altro codice nello stile dell'SDK versione 8.

Vantaggi e limitazioni della versione 9

La versione 9 completamente modularizzata presenta i seguenti vantaggi rispetto alle versioni precedenti:

  • La versione 9 consente di ridurre notevolmente le dimensioni dell'app. Adotta il formato del modulo JavaScript moderno, consentendo le pratiche di "tree shaking" in cui vengono importati solo gli elementi necessari per l'app. A seconda dell'app, il tree-shaking con la versione 9 può comportare un risparmio di kilobyte dell'80% rispetto a un'app simile creata utilizzando la versione 8.
  • La versione 9 continuerà a trarre vantaggio dallo sviluppo continuo delle funzionalità, mentre la versione 8 verrà bloccata in un secondo momento.