אם אתם משתמשים באפליקציות עם Firebase web API עם מרחב שמות, מספריית compat ועד גרסה 8 או גרסאות קודמות, כדאי לכם לעבור ל-modular API לפי ההוראות במדריך הזה.
המדריך הזה מבוסס על ההנחה שאתם מכירים את ה-API עם מרחב השמות, ושתשתמשו בכלי לאריזת מודולים כמו webpack או Rollup כדי לשדרג את האפליקציה ולפתח אותה באופן מודולרי.
מומלץ מאוד להשתמש בכלי לאריזת מודולים בסביבת הפיתוח. אם לא תשתמשו בכלי כזה, לא תוכלו ליהנות מהיתרונות העיקריים של ה-API המודולרי, כמו הקטנת נפח האפליקציה. כדי להתקין את ה-SDK, צריך את npm או את yarn.
השלבים לשדרוג במדריך הזה מבוססים על אפליקציית אינטרנט דמיונית שמשתמשת בערכות ה-SDK של Authentication ו-Cloud Firestore. הדוגמאות האלה יעזרו לכם להבין את המושגים ואת השלבים המעשיים שצריך לבצע כדי לשדרג את כל ערכות ה-SDK הנתמכות של Firebase לאינטרנט.
מידע על הספריות של מרחב השמות (compat)
יש שני סוגים של ספריות זמינות ל-SDK של Firebase לאינטרנט:
מודולרי: ממשק API חדש שנועד לאפשר tree-shaking (הסרה של קוד שלא בשימוש) כדי שהאפליקציה שלכם תהיה קטנה ומהירה ככל האפשר.
מרחב שמות (
compat): ממשק API מוכר שתואם באופן מלא לגרסאות הקודמות של ה-SDK, ומאפשר לכם לשדרג בלי לשנות את כל קוד Firebase בבת אחת. לספריות תאימות יש יתרונות קטנים, אם בכלל, מבחינת גודל או ביצועים בהשוואה לספריות המקבילות שלהן במרחב השמות.
המדריך הזה מבוסס על ההנחה שתשתמשו בספריות התאימות כדי לשדרג. הספריות האלה מאפשרות לכם להמשיך להשתמש בקוד עם מרחב שמות לצד קוד שעבר refactoring ל-modular API. זה אומר שתוכלו לקמפל את האפליקציה ולנפות באגים בקלות רבה יותר במהלך תהליך השדרוג.
באפליקציות עם חשיפה קטנה מאוד ל-Firebase Web SDK (לדוגמה, אפליקציה שמבצעת רק קריאה פשוטה לממשקי ה-API של Authentication), יכול להיות שיהיה מעשי לשנות את הקוד הישן של מרחב השמות בלי להשתמש בספריות התאימות. אם אתם משדרגים אפליקציה כזו, אתם יכולים לפעול לפי ההוראות במדריך הזה לגבי "ה-API המודולרי" בלי להשתמש בספריות התאימות.
מידע על תהליך השדרוג
כל שלב בתהליך השדרוג מוגדר כך שתוכלו לסיים את עריכת המקור של האפליקציה, ואז לקמפל ולהריץ אותה בלי תקלות. לסיכום, כדי לשדרג אפליקציה:
מוסיפים לאפליקציה את הספריות המודולריות ואת ספריות התאימות.
מעדכנים את הצהרות הייבוא בקוד ל-compat.
משכתבים את הקוד של מוצר אחד (לדוגמה, Authentication) לסגנון מודולרי.
(אופציונלי) כדי ליהנות מהיתרון של גודל האפליקציה ב-Authentication, לפני שממשיכים, מסירים את ספריית התאימות של Authentication ואת קוד התאימות של Authentication.
משכתבים את הפונקציות של כל מוצר (לדוגמה, Cloud Firestore, FCM וכו') לסגנון המודולרי, מקמפלים ובודקים עד שכל האזורים מוכנים.
מעדכנים את קוד האתחול לסגנון המודולרי.
מסירים מהאפליקציה את כל הצהרות התאימות וקוד התאימות שנותרו.
הורדת הגרסה העדכנית של ה-SDK
כדי להתחיל, צריך להוריד את הספריות המודולריות ואת ספריות התאימות באמצעות npm:
npm i firebase@13.4.0 # OR yarn add firebase@13.4.0
עדכון הייבוא לתאימות
כדי שהקוד ימשיך לפעול אחרי עדכון יחסי התלות, צריך לשנות את הצהרות הייבוא כך שישתמשו בגרסת ה-compat של כל ייבוא. לדוגמה:
לפני: גרסה 8 או גרסאות קודמות
import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';
אחרי: compat
// compat packages are API compatible with namespaced code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';
לארגן את הקוד מחדש לסגנון מודולרי
למרות שממשקי ה-API של מרחב השמות מבוססים על מרחב שמות משורשר בנקודות ועל דפוס שירות, הגישה המודולרית פירושה שהקוד שלכם יאורגן בעיקר סביב פונקציות. ב-modular API, החבילה firebase/app וחבילות אחרות לא מחזירות ייצוא מקיף שמכיל את כל השיטות מהחבילה. במקום זאת, החבילות מייצאות פונקציות נפרדות.
ב-modular API, השירותים מועברים כארגומנט הראשון, ואז הפונקציה משתמשת בפרטי השירות כדי לבצע את השאר. בדוגמאות הבאות מוסבר איך לשנות את הקוד של הקריאות ל-API של Authentication ו-Cloud Firestore.
דוגמה 1: שכתוב של פונקציית Authentication
לפני: compat
קוד התאימות זהה לקוד של מרחב השמות, אבל הייבוא השתנה.
import firebase from "firebase/compat/app";
import "firebase/compat/auth";
const auth = firebase.auth();
auth.onAuthStateChanged(user => {
// Check for user status
});
אחרי: מודולרי
הפונקציה getAuth מקבלת את firebaseApp בתור הפרמטר הראשון שלה. הפונקציה onAuthStateChanged לא משורשרת מהמופע של auth כמו ב-namespaced API. במקום זאת, זו פונקציה חינמית שמקבלת את auth כפרמטר הראשון שלה.
import { getAuth, onAuthStateChanged } from "firebase/auth";
const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
// Check for user status
});
עדכון הטיפול בשיטת האימות getRedirectResult
ה-API המודולרי מציג שינוי תוכנה שעלול לגרום לכשל ב-getRedirectResult. כשלא מתבצעת קריאה לפעולת הפניה אוטומטית, ה-modular API מחזיר null, בניגוד ל-namespaced API שמחזיר UserCredential עם משתמש null.
לפני: compat
const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
return null;
}
return result;
אחרי: מודולרי
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;
דוגמה 2: שכתוב פונקציה של Cloud Firestore
לפני: 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);
});
אחרי: מודולרי
הפונקציה getFirestore מקבלת את firebaseApp כפרמטר הראשון שלה, שהוחזר מ-initializeApp בדוגמה קודמת. שימו לב שהקוד ליצירת שאילתה שונה מאוד ב-modular API. באופן ספציפי, אין שרשור, ושיטות כמו query או where חשופות עכשיו כפונקציות חופשיות.
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());
});
עדכון ההפניות ל-Firestore DocumentSnapshot.exists
ה-API המודולרי כולל שינוי תוכנה שעלול לגרום לכשל, שבו המאפיין firestore.DocumentSnapshot.exists השתנה לmethod. הפונקציונליות זהה במהותה (בדיקה אם מסמך קיים), אבל צריך לארגן את הקוד מחדש כדי להשתמש בשיטה החדשה יותר, כפי שמוצג:
Before:compat
if (snapshot.exists) {
console.log("the document exists");
}
אחרי: מודולרי
if (snapshot.exists()) {
console.log("the document exists");
}
דוגמה 3: שילוב של סגנונות קוד מודולריים ומרחבי שמות
שימוש בספריות התאימות במהלך השדרוג מאפשר לכם להמשיך להשתמש בקוד עם מרחב שמות לצד קוד שעבר refactoring ל-modular API.
זה אומר שאתם יכולים להשאיר את הקוד הקיים של מרחב השמות של Cloud Firestore בזמן שאתם מארגנים את הקוד מחדש של Authentication או קוד אחר של Firebase SDK לסגנון המודולרי, ועדיין לקמפל את האפליקציה עם שני סגנונות הקוד.
אותו דבר נכון לגבי קוד API מודולרי ומרחב שמות בתוך מוצר, כמו Cloud Firestore. סגנונות קוד חדשים וישנים יכולים להתקיים יחד, כל עוד מייבאים את חבילות התאימות.
import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'
const docRef = firebase.firestore().doc();
getDoc(docRef);
חשוב לזכור: למרות שהאפליקציה תעבור הידור, לא תיהנו מהיתרונות של הקוד המודולרי מבחינת גודל האפליקציה עד שתסירו לגמרי את הצהרות התאימות והקוד מהאפליקציה.
עדכון קוד האתחול
מעדכנים את קוד האתחול של האפליקציה כך שישתמש בתחביר מודולרי. חשוב לעדכן את הקוד הזה אחרי שסיימתם לשנות את כל הקוד באפליקציה. הסיבה לכך היא שהפונקציה firebase.initializeApp() מאתחלת את המצב הגלובלי גם של ממשקי ה-API התואמים וגם של ממשקי ה-API המודולריים, ואילו הפונקציה המודולרית initializeApp() מאתחלת רק את המצב של ממשקי ה-API המודולריים.
לפני: compat
import firebase from "firebase/compat/app"
firebase.initializeApp({ /* config */ });
אחרי: מודולרי
import { initializeApp } from "firebase/app"
const firebaseApp = initializeApp({ /* config */ });
הסרת קוד תאימות
כדי ליהנות מהיתרונות של ה-modular API מבחינת הגודל, בסופו של דבר צריך להמיר את כל הקריאות לסגנון המודולרי שמוצג למעלה ולהסיר את כל הצהרות ה-import "firebase/compat/* מהקוד. בסיום, לא אמורות להיות הפניות למרחב השמות הגלובלי firebase.* או לקוד אחר בסגנון של namespaced API.
שימוש בספריית התאימות מהחלון
ה-API המודולרי מותאם לעבודה עם מודולים ולא עם האובייקט window של הדפדפן. בגרסאות קודמות של הספרייה אפשר היה לטעון את Firebase ולנהל אותו באמצעות מרחב השמות window.firebase. לא מומלץ להשתמש בשיטה הזו, כי היא לא מאפשרת להסיר קוד שלא בשימוש.
עם זאת, גרסת התאימות של JavaScript SDK פועלת עם window למפתחים שמעדיפים לא להתחיל מיד את תהליך השדרוג המודולרי.
<script src="https://www.gstatic.com/firebasejs/13.4.0/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/13.4.0/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/13.4.0/firebase-auth-compat.js"></script>
<script>
const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
const db = firebaseApp.firestore();
const auth = firebaseApp.auth();
</script>
ספריית התאימות משתמשת בקוד מודולרי מאחורי הקלעים ומספקת לו את אותו API כמו ה-namespaced API. כלומר, אפשר לעיין במאמרי העזרה של namespaced API ובקטעי קוד של מרחב שמות כדי לקבל פרטים. השיטה הזו לא מומלצת לשימוש לטווח ארוך, אלא כהתחלה לשדרוג לספרייה המודולרית המלאה.
היתרונות והמגבלות של ה-SDK המודולרי
ל-SDK המודולרי לחלוטין יש את היתרונות הבאים בהשוואה לגרסאות קודמות:
ה-SDK המודולרי מאפשר להקטין באופן משמעותי את גודל האפליקציה. הוא משתמש בפורמט המודול המודרני של JavaScript, שמאפשר שיטות של "tree shaking" שבהן מייבאים רק את פריטי המידע שהאפליקציה צריכה. בהתאם לאפליקציה, שימוש ב-tree shaking עם ה-SDK המודולרי יכול להפחית את מספר הקילובייטים ב-80% בהשוואה לאפליקציה דומה שנוצרה באמצעות namespaced API.
ערכת ה-SDK המודולרית תמשיך ליהנות מפיתוח תכונות שוטף, ואילו ה-namespaced API לא.