Aplikacje korzystające z dowolnego interfejsu Firebase web API w przestrzeni nazw z bibliotek compat w wersji 8 lub starszej powinny przejść na modułowy interfejs API, korzystając z instrukcji w tym przewodniku.
W tym przewodniku zakładamy że znasz interfejs API w przestrzeni nazw 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 deweloperskim. 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 potrzebujesz 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 w 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) i zmniejszyć rozmiar aplikacji internetowej oraz przyspieszyć jej działanie.
- W 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 jednoczesnego zmieniania 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 w 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 w 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 w 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 „modułowego interfejsu API” bez użycia bibliotek Compat.
Proces 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 żadnych problemów. 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 dla jednego produktu (np. Authentication) do stylu modułowego.
- Opcjonalnie: w tym momencie usuń bibliotekę Authentication Compat i kod Compat dla Authentication, aby przed kontynuowaniem skorzystać z zalet modułowego interfejsu API w zakresie rozmiaru aplikacji.Authentication
- Refaktoryzuj funkcje dla 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 Compat i kod Compat.
Pobierz najnowszą wersję 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
Zaktualizuj importy 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:
Wcześniej: wersja 8 lub starsza
import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';
Potem: Compat
// compat packages are API compatible with namespaced code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';
Refaktoryzuj do stylu modułowego
Interfejsy API w przestrzeni nazw są oparte na wzorcu przestrzeni nazw i usług połączonych kropkami, natomiast podejście modułowe oznacza, że kod będzie zorganizowany głównie wokół funkcji. W modułowym interfejsie 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 modułowym interfejsie 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
Wcześniej: Compat
Kod Compat jest identyczny z kodem w 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
});
Potem: modułowy
Funkcja getAuth przyjmuje firebaseApp jako pierwszy parametr.
Funkcja onAuthStateChanged
nie jest połączona z instancją auth, jak w przypadku
interfejsu API w przestrzeni nazw. 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
});
Zaktualizuj obsługę metody Auth getRedirectResult
Modułowy interfejs API wprowadza zmianę powodującą niezgodność w getRedirectResult. Gdy nie jest wywoływana żadna operacja przekierowania, modułowy interfejs API zwraca null, w przeciwieństwie do interfejsu API w przestrzeni nazw, który zwracał UserCredential z użytkownikiem null.
Wcześniej: Compat
const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
return null;
}
return result;
Potem: 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
Wcześniej: 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);
});
Potem: 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());
});
Zaktualizuj odwołania 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:
Wcześniej:Compat
if (snapshot.exists) {
console.log("the document exists");
}
Potem: modułowy
if (snapshot.exists()) {
console.log("the document exists");
}
Przykład 3. Łączenie stylów kodu w przestrzeni nazw i modułowego
Używanie bibliotek Compat podczas uaktualniania umożliwia dalsze używanie kodu w przestrzeni nazw obok kodu refaktoryzowanego pod kątem modułowego interfejsu API. Oznacza to, że możesz zachować istniejący kod w przestrzeni nazw dla Cloud Firestore refaktoryzując Authentication lub innego pakietu Firebase SDK do stylu modułowego, i nadal kompilować aplikację z oboma stylami kodu. To samo dotyczy kodu interfejsu API w 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 z modułowego kodu w zakresie rozmiaru aplikacji, dopóki całkowicie nie usuniesz z niej instrukcji i kodu Compat.
Zaktualizuj kod inicjujący
Zaktualizuj kod inicjujący aplikację, 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 Compat, jak i modułowych, natomiast funkcja modułowa
initializeApp() inicjuje tylko stan modułowy.
Wcześniej: Compat
import firebase from "firebase/compat/app"
firebase.initializeApp({ /* config */ });
Potem: modułowy
import { initializeApp } from "firebase/app"
const firebaseApp = initializeApp({ /* config */ });
Usuń kod Compat
Aby skorzystać z zalet modułowego interfejsu API w zakresie rozmiaru, 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 interfejsu API w przestrzeni nazw.
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 nie chcą od razu rozpoczynać 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 w przestrzeni nazw. Oznacza to, że szczegółowe informacje znajdziesz w dokumentacji interfejsu API w przestrzeni nazw i fragmentach kodu w 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. Korzysta z nowoczesnego formatu 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ą interfejsu API w przestrzeni nazw.
- Modułowy pakiet SDK będzie nadal korzystać z rozwoju funkcji, natomiast interfejs API w przestrzeni nazw nie będzie.