Aplikacje, które używają dowolnego interfejsu Firebase web API z przestrzenią nazw, z bibliotek compat w wersji 8 lub starszej, powinny przejść na Modular API, korzystając z instrukcji w tym przewodniku.
W tym przewodniku zakładamy, że znasz interfejs Namespaced API i że do uaktualniania i dalszego tworzenia aplikacji modułowych będziesz używać usługi tworzenia pakietów modułów, takiej jak webpack lub Rollup.
Zdecydowanie zalecamy używanie usługi tworzenia pakietów modułów w środowisku programistycznym. Jeśli nie będziesz jej używać, nie będziesz mieć możliwości korzystania z głównych zalet modułowego interfejsu API, czyli mniejszego rozmiaru aplikacji. Do zainstalowania pakietu SDK będziesz potrzebować npm lub yarn.
Kroki uaktualnienia opisane w tym przewodniku będą oparte na fikcyjnej aplikacji internetowej, która korzysta z pakietów SDK Authentication i Cloud Firestore. Dzięki pracy z przykładami możesz opanować koncepcje i praktyczne kroki wymagane do uaktualnienia wszystkich obsługiwanych pakietów Firebase web SDK.
Biblioteki z przestrzenią nazw (compat)
Dostępne są 2 typy bibliotek dla pakietu Firebase web SDK:
- Modułowe – nowy interfejs API zaprojektowany tak, aby ułatwić usuwanie nieużywanego kodu (tree-shaking), dzięki czemu aplikacja internetowa będzie jak najmniejsza i najszybsza.
- Z przestrzenią nazw (
compat) – znany interfejs API, który jest w pełni zgodny z wcześniejszymi wersjami pakietu SDK, co pozwala na uaktualnienie bez konieczności jednoczesnej zmiany całego kodu Firebase. Biblioteki Compat nie mają żadnych lub prawie żadnych zalet w zakresie rozmiaru i wydajności w porównaniu z ich odpowiednikami z przestrzenią nazw.
W tym przewodniku zakładamy, że do ułatwienia uaktualnienia będziesz używać bibliotek Compat. Te biblioteki umożliwiają dalsze używanie kodu z przestrzenią nazw obok kodu refaktoryzowanego pod kątem modułowego interfejsu API. Oznacza to, że podczas procesu uaktualniania możesz łatwiej kompilować i debugować aplikację.
W przypadku aplikacji, które w niewielkim stopniu korzystają z pakietu Firebase web SDK (np. aplikacji, która wykonuje tylko proste wywołanie interfejsów Authentication API), refaktoryzacja starszego kodu z przestrzenią nazw bez użycia bibliotek Compat może być praktyczna. Jeśli uaktualniasz taką aplikację, możesz postępować zgodnie z instrukcjami w tym przewodniku dotyczącymi „Modular API” bez użycia bibliotek Compat.
Informacje o procesie uaktualniania
Każdy etap procesu uaktualniania jest tak skonstruowany, aby można było zakończyć edytowanie kodu źródłowego aplikacji, a następnie skompilować i uruchomić ją bez przerw. Podsumowując, aby uaktualnić aplikację, wykonaj te czynności:
- Dodaj do aplikacji biblioteki modułowe i biblioteki Compat.
- Zaktualizuj instrukcje importu w kodzie do Compat.
- Refaktoryzuj kod jednego produktu (np. Authentication) do stylu modułowego.
- Opcjonalnie: w tym momencie usuń bibliotekę Authentication Compat i kod Compat dla Authentication, aby przed kontynuowaniem uzyskać korzyści w zakresie rozmiaru aplikacji w przypadku Authentication.
- Refaktoryzuj funkcje każdego produktu (np. Cloud Firestore, FCM, itp.) do stylu modułowego, kompilując i testując, aż wszystkie obszary zostaną ukończone.
- Zaktualizuj kod inicjujący do stylu modułowego.
- Usuń z aplikacji wszystkie pozostałe instrukcje i kod Compat.
Pobieranie najnowszej wersji pakietu SDK
Aby rozpocząć, pobierz biblioteki modułowe i biblioteki Compat za pomocą npm:
npm i firebase@12.15.0 # OR yarn add firebase@12.15.0
Aktualizowanie importów do Compat
Aby kod działał po zaktualizowaniu zależności, zmień instrukcje importu tak, aby używały wersji „compat” każdego importu. Przykład:
Przed: wersja 8 lub starsza
import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';
Po: Compat
// compat packages are API compatible with namespaced code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';
Refaktoryzacja do stylu modułowego
Interfejsy API z przestrzenią nazw są oparte na wzorcu przestrzeni nazw i usługi połączonych kropkami, natomiast podejście modułowe oznacza, że kod będzie zorganizowany głównie wokół funkcji. W Modular API pakiet firebase/app i inne pakiety nie zwracają kompleksowego eksportu, który zawiera wszystkie metody z pakietu. Zamiast tego pakiety eksportują poszczególne funkcje.
W Modular API usługi są przekazywane jako pierwszy argument, a funkcja używa szczegółów usługi do wykonania pozostałych czynności. Zobaczmy, jak to działa na 2 przykładach, które refaktoryzują wywołania interfejsów Authentication i Cloud Firestore API.
Przykład 1. Refaktoryzacja funkcji Authentication
Przed: Compat
Kod Compat jest identyczny z kodem z przestrzenią nazw, ale importy zostały zmienione.
import firebase from "firebase/compat/app";
import "firebase/compat/auth";
const auth = firebase.auth();
auth.onAuthStateChanged(user => {
// Check for user status
});
Po: modułowy
Funkcja getAuth przyjmuje firebaseApp jako pierwszy parametr.
Funkcja onAuthStateChanged
nie jest połączona z instancją auth, jak w przypadku
Namespaced API. Jest to funkcja wolna, która przyjmuje auth jako pierwszy parametr.
import { getAuth, onAuthStateChanged } from "firebase/auth";
const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
// Check for user status
});
Aktualizowanie obsługi metody Auth getRedirectResult
Modular API wprowadza zmianę powodującą niezgodność w getRedirectResult. Gdy nie jest wywoływana żadna operacja przekierowania, Modular API zwraca null, w przeciwieństwie do Namespaced API, który zwracał UserCredential z użytkownikiem null.
Przed: Compat
const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
return null;
}
return result;
Po: modułowy
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;
Przykład 2. Refaktoryzacja funkcji Cloud Firestore
Przed: 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);
});
Po: modułowy
Funkcja getFirestore przyjmuje firebaseApp jako pierwszy parametr, który został zwrócony przez initializeApp w poprzednim przykładzie. Zwróć uwagę, jak bardzo różni się kod tworzący zapytanie w modułowym interfejsie API. Nie ma łańcuchów, a metody takie jak query czy where są teraz udostępniane jako funkcje wolne.
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());
});
Aktualizowanie odwołań do Firestore DocumentSnapshot.exists
Modułowy interfejs API wprowadza zmianę powodującą niezgodność, w której właściwość firestore.DocumentSnapshot.exists została zmieniona na metodę. Funkcja jest zasadniczo taka sama (sprawdzanie, czy dokument istnieje), ale musisz refaktoryzować kod, aby używać nowszej metody, jak pokazano poniżej:
Przed:Compat
if (snapshot.exists) {
console.log("the document exists");
}
Po: modułowy
if (snapshot.exists()) {
console.log("the document exists");
}
Przykład 3. Łączenie stylów kodu z przestrzenią nazw i modułowego
Używanie bibliotek Compat podczas uaktualniania pozwala na dalsze używanie kodu z przestrzenią nazw obok kodu refaktoryzowanego pod kątem Modular API. Oznacza to, że możesz zachować istniejący kod z przestrzenią nazw dla Cloud Firestore podczas gdy refaktoryzujesz Authentication lub inny kod pakietu Firebase SDK do stylu modułowego, i nadal możesz pomyślnie skompilować aplikację z oboma stylami kodu. To samo dotyczy kodu interfejsu API z przestrzenią nazw i modułowego w obrębie produktu, takiego jak Cloud Firestore. Nowe i stare style kodu mogą współistnieć, o ile importujesz pakiety Compat:
import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'
const docRef = firebase.firestore().doc();
getDoc(docRef);
Pamiętaj, że chociaż aplikacja będzie się kompilować, nie uzyskasz korzyści w zakresie rozmiaru aplikacji wynikających z kodu modułowego, dopóki całkowicie nie usuniesz z aplikacji instrukcji i kodu Compat.
Aktualizowanie kodu inicjującego
Zaktualizuj kod inicjujący aplikacji, aby używać składni modułowej. Ważne jest
aby zaktualizować ten kod po zakończeniu refaktoryzacji całego
kodu w aplikacji. Wynika to z tego, że firebase.initializeApp() inicjuje stan globalny
zarówno dla interfejsów API Compat, jak i modułowych, natomiast funkcja modułowa
initializeApp() inicjuje tylko stan modułowy.
Przed: Compat
import firebase from "firebase/compat/app"
firebase.initializeApp({ /* config */ });
Po: modułowy
import { initializeApp } from "firebase/app"
const firebaseApp = initializeApp({ /* config */ });
Usuwanie kodu Compat
Aby uzyskać korzyści w zakresie rozmiaru wynikające z Modular API, musisz ostatecznie przekonwertować wszystkie wywołania na styl modułowy pokazany powyżej i usunąć z kodu wszystkie instrukcje import "firebase/compat/*. Po zakończeniu nie powinno być już żadnych odwołań do globalnej przestrzeni nazw firebase.* ani żadnego innego kodu w stylu Namespaced API.
Używanie biblioteki Compat z okna
Modułowy interfejs API jest zoptymalizowany do współpracy z modułami, a nie z obiektem window przeglądarki. Wcześniejsze wersje biblioteki umożliwiały wczytywanie i zarządzanie Firebase za pomocą przestrzeni nazw window.firebase. Nie zalecamy tego, ponieważ nie pozwala to na eliminowanie nieużywanego kodu.
Jednak wersja Compat pakietu JavaScript SDK działa z window w przypadku deweloperów, którzy wolą nie rozpoczynać od razu ścieżki uaktualniania modułowego.
<script src="https://www.gstatic.com/firebasejs/12.15.0/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/12.15.0/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/12.15.0/firebase-auth-compat.js"></script>
<script>
const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
const db = firebaseApp.firestore();
const auth = firebaseApp.auth();
</script>
Biblioteka zgodności używa pod maską kodu modułowego i udostępnia go za pomocą tego samego interfejsu API co interfejs API z przestrzenią nazw. Oznacza to, że szczegóły znajdziesz w dokumentacji interfejsu API z przestrzenią nazw i fragmentach kodu z przestrzenią nazw. Ta metoda nie jest zalecana do długotrwałego użytku, ale może być dobrym początkiem uaktualnienia do w pełni modułowej biblioteki.
Zalety i ograniczenia modułowego pakietu SDK
W pełni modułowy pakiet SDK ma te zalety w porównaniu z wcześniejszymi wersjami:
- Modułowy pakiet SDK umożliwia znaczne zmniejszenie rozmiaru aplikacji. Przyjmuje nowoczesny format modułu JavaScript, co pozwala na stosowanie praktyk „tree-shaking”, w których importujesz tylko te artefakty, których potrzebuje Twoja aplikacja. W zależności od aplikacji tree-shaking z modułowym pakietem SDK może zmniejszyć rozmiar aplikacji o 80% w porównaniu z podobną aplikacją utworzoną za pomocą Namespaced API.
- Modułowy pakiet SDK będzie nadal korzystać z rozwoju funkcji, natomiast Namespaced API nie będzie.