Ad alanlı API'den modüler API'ye yükseltin

Şu anda compat kitaplıklarından 8 veya önceki sürümlere kadar herhangi bir ad alanlı Firebase Web API kullanan uygulamalar, bu kılavuzdaki talimatları kullanarak modüler API'ye geçmeyi düşünmelidir.

Bu kılavuz, ad alanlı API'ye aşina olduğunuzu ve yükseltme ve devam eden modüler uygulama geliştirme için webpack veya Rollup gibi bir modül paketleyiciden yararlanacağınızı varsayar.

Geliştirme ortamınızda bir modül paketleyici kullanmanız şiddetle tavsiye edilir. Birini kullanmazsanız, modüler API'nin küçültülmüş uygulama boyutundaki ana avantajlarından yararlanamazsınız. SDK'yı yüklemek için npm veya yarn gerekir.

Bu kılavuzdaki yükseltme adımları, Kimlik Doğrulama ve Cloud Firestore SDK'larını kullanan hayali bir web uygulamasını temel alacaktır. Örnekler üzerinde çalışarak, desteklenen tüm Firebase Web SDK'larını yükseltmek için gereken kavramlarda ve pratik adımlarda uzmanlaşabilirsiniz.

Ad alanlı ( compat ) kitaplıklar hakkında

Firebase Web SDK'sı için iki tür kitaplık vardır:

  • Modüler - web uygulamanızı olabildiğince küçük ve hızlı hale getirmek için ağaç sallamayı (kullanılmayan kodun kaldırılması) kolaylaştırmak için tasarlanmış yeni bir API yüzeyi.
  • Namespaced ( compat ) - SDK'nın önceki sürümleriyle tamamen uyumlu olan ve tüm Firebase kodunuzu bir kerede değiştirmeden yükseltme yapmanıza olanak tanıyan tanıdık bir API yüzeyi. Uyumlu kitaplıkların, ad alanlı muadillerine göre çok az boyut veya performans avantajı vardır veya hiç yoktur.

Bu kılavuz, yükseltmenizi kolaylaştırmak için uyumluluk kitaplıklarından yararlanacağınızı varsayar. Bu kitaplıklar, modüler API için yeniden düzenlenen kodun yanı sıra ad alanlı kodu kullanmaya devam etmenize olanak tanır. Bu, yükseltme sürecinde çalışırken uygulamanızı daha kolay derleyebileceğiniz ve hata ayıklayabileceğiniz anlamına gelir.

Firebase Web SDK'sına çok az maruz kalan uygulamalar için (örneğin, Kimlik Doğrulama API'lerine yalnızca basit bir çağrı yapan bir uygulama), uyumluluk kitaplıklarını kullanmadan eski ad alanlı kodu yeniden düzenlemek pratik olabilir. Böyle bir uygulamayı yükseltiyorsanız, uyumluluk kitaplıklarını kullanmadan "modüler API" için bu kılavuzdaki talimatları uygulayabilirsiniz.

Yükseltme işlemi hakkında

Yükseltme işleminin her adımı, uygulamanız için kaynağı düzenlemeyi tamamlayabilmeniz ve ardından onu kesinti olmadan derleyip çalıştırabilmeniz için kapsamlıdır. Özetle, bir uygulamayı yükseltmek için şunları yapacaksınız:

  1. Modüler kitaplıkları ve uyumluluk kitaplıklarını uygulamanıza ekleyin.
  2. Kodunuzdaki import deyimlerini uyumlu olacak şekilde güncelleyin.
  3. Tek bir ürün için (örneğin, Kimlik Doğrulama) kodu modüler stilde yeniden düzenleyin.
  4. İsteğe bağlı: Bu noktada, devam etmeden önce Kimlik Doğrulama için uygulama boyutu avantajını gerçekleştirmek üzere Kimlik Doğrulama uyumlu kitaplığını ve Kimlik Doğrulaması için uyumluluk kodunu kaldırın.
  5. Her ürün için (örneğin, Cloud Firestore, FCM, vb.) işlevleri modüler stilde yeniden düzenleyin, tüm alanlar tamamlanana kadar derleme ve test edin.
  6. Başlatma kodunu modüler stile güncelleyin.
  7. Uygulamanızdan kalan tüm uyumluluk ifadelerini ve uyumluluk kodunu kaldırın.

SDK'nın en son sürümünü edinin

Başlamak için npm kullanarak modüler kitaplıkları ve uyumlu kitaplıkları edinin:

npm i firebase@10.3.1

# OR

yarn add firebase@10.3.1

İçe aktarmaları uyumluluk için güncelle

Bağımlılıklarınızı güncelledikten sonra kodunuzun çalışmaya devam etmesi için, içe aktarma ifadelerinizi her içe aktarma işleminin "uyumlu" sürümünü kullanacak şekilde değiştirin. Örneğin:

Önce: sürüm 8 veya öncesi

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

Sonra: uyumluluk

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

Modüler stile yeniden düzenleme

Ad alanlı API'ler, nokta zincirli bir ad alanı ve hizmet modelini temel alırken, modüler yaklaşım, kodunuzun temel olarak functions etrafında organize edileceği anlamına gelir. Modüler API'de, firebase/app paketi ve diğer paketler, paketteki tüm yöntemleri içeren kapsamlı bir dışa aktarma döndürmez. Bunun yerine, paketler bireysel işlevleri dışa aktarır.

Modüler API'de, hizmetler ilk bağımsız değişken olarak iletilir ve ardından işlev, gerisini halletmek için hizmetin ayrıntılarını kullanır. Kimlik Doğrulama ve Cloud Firestore API'lerine yapılan çağrıları yeniden düzenleyen iki örnekte bunun nasıl çalıştığını inceleyelim.

Örnek 1: Bir Kimlik Doğrulama işlevini yeniden düzenleme

Önce: uyumlu

Uyumlu kod, ad alanlı kodla aynıdır, ancak içe aktarmalar değişmiştir.

import firebase from "firebase/compat/app";
import "firebase/compat/auth";

const auth = firebase.auth();
auth.onAuthStateChanged(user => { 
  // Check for user status
});

Sonra: modüler

getAuth işlevi, ilk parametresi olarak firebaseApp alır. onAuthStateChanged işlevi, ad alanlı API'de olduğu gibi auth örneğinden zincirlenmez; bunun yerine, ilk parametresi olarak auth alan ücretsiz bir işlevdir.

import { getAuth, onAuthStateChanged } from "firebase/auth";

const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
  // Check for user status
});

Auth yöntemi getRedirectResult güncellenmesi

Modüler API, getRedirectResult çok önemli bir değişiklik sunar. Yönlendirme işlemi çağrılmadığı zaman, modüler API, null kullanıcıyla bir UserCredential döndüren ad alanlı API'nin aksine null değerini döndürür.

Önce: uyumlu

const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
  return null;
}
return result;

Sonra: modüler

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;

Örnek 2: Cloud Firestore işlevini yeniden düzenleme

Önce: uyumlu

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);
    });

Sonra: modüler

getFirestore işlevi, firebaseApp ilk parametresi olarak alır; bu, daha önceki bir örnekte initializeApp döndürülmüştür. Bir sorgu oluşturma kodunun modüler API'de ne kadar farklı olduğuna dikkat edin; zincirleme yoktur ve query veya where gibi yöntemler artık ücretsiz işlevler olarak sunulur.

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 referanslarını güncelleyin

Modüler API, firestore.DocumentSnapshot.exists özelliğinin bir yöntem olarak değiştirildiği önemli bir değişiklik sunar. İşlevsellik temelde aynıdır (bir belgenin var olup olmadığını test etme), ancak gösterildiği gibi daha yeni yöntemi kullanmak için kodunuzu yeniden düzenlemeniz gerekir:

Önce: uyumlu

if (snapshot.exists) {
  console.log("the document exists");
}

Sonra: modüler

if (snapshot.exists()) {
  console.log("the document exists");
}

Örnek 3: ad alanlı ve modüler kod stillerini birleştirme

Yükseltme sırasında uyumluluk kitaplıklarını kullanmak, modüler API için yeniden düzenlenen kodun yanı sıra ad alanlı kodu kullanmaya devam etmenizi sağlar. Bu, Authentication veya diğer Firebase SDK kodunu modüler stille yeniden düzenlerken Cloud Firestore için mevcut ad alanlı kodu tutabileceğiniz ve uygulamanızı her iki kod stiliyle de başarıyla derleyebileceğiniz anlamına gelir. Aynı durum, Cloud Firestore gibi bir ürün içindeki ad alanlı ve modüler API kodu için de geçerlidir; uyumluluk paketlerini içe aktardığınız sürece yeni ve eski kod stilleri bir arada bulunabilir:

import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'

const docRef = firebase.firestore().doc();
getDoc(docRef);

Uygulamanız derlenecek olsa da, uygulamanızdan uyumluluk deyimlerini ve kodunu tamamen kaldırana kadar modüler kodun uygulama boyutu avantajlarını elde edemeyeceğinizi unutmayın.

Başlatma kodunu güncelle

Modüler sözdizimini kullanmak için uygulamanızın başlatma kodunu güncelleyin. Uygulamanızdaki tüm kodu yeniden düzenlemeyi tamamladıktan sonra bu kodu güncellemeniz önemlidir; Bunun nedeni firebase.initializeApp() hem uyumlu hem de modüler API'ler için genel durumu başlatması, oysa modüler initializeApp() işlevinin yalnızca modüler için durumu başlatmasıdır.

Önce: uyumlu

import firebase from "firebase/compat/app"

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

Sonra: modüler

import { initializeApp } from "firebase/app"

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

Uyumlu kodu kaldır

Modüler API'nin boyut avantajlarını gerçekleştirmek için, sonunda tüm çağrıları yukarıda gösterilen modüler stile dönüştürmeli ve import "firebase/compat/* deyimlerinin tümünü kodunuzdan kaldırmalısınız. İşiniz bittiğinde, daha fazla referans olmamalıdır. firebase.* global ad alanına veya ad alanlı API stilindeki diğer herhangi bir koda.

Uyumluluk kitaplığını pencereden kullanma

Modüler API, tarayıcının window nesnesi yerine modüllerle çalışacak şekilde optimize edilmiştir. Kitaplığın önceki sürümleri, window.firebase ad alanını kullanarak Firebase'in yüklenmesine ve yönetilmesine izin veriyordu. Kullanılmayan kod elemesine izin vermediğinden, bunun ileriye götürülmesi önerilmez. Ancak JavaScript SDK'nın uyumlu sürümü, modüler yükseltme yoluna hemen başlamamayı tercih eden geliştiriciler için window birlikte çalışır.

<script src="https://www.gstatic.com/firebasejs/10.3.1/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.3.1/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.3.1/firebase-auth-compat.js"></script>
<script>
   const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
   const db = firebaseApp.firestore();
   const auth = firebaseApp.auth();
</script>

Uyumluluk kitaplığı, başlık altında modüler kod kullanır ve ona ad alanlı API ile aynı API'yi sağlar; bu, ayrıntılar için ad alanlı API referansına ve ad alanlı kod parçacıklarına başvurabileceğiniz anlamına gelir. Bu yöntem, uzun süreli kullanım için değil, tamamen modüler kitaplığa yükseltme için bir başlangıç ​​olarak önerilir.

Modüler SDK'nın avantajları ve sınırlamaları

Tamamen modüler hale getirilmiş SDK, önceki sürümlere göre şu avantajlara sahiptir:

  • Modüler SDK, önemli ölçüde azaltılmış bir uygulama boyutu sağlar. Yalnızca uygulamanızın ihtiyaç duyduğu yapıları içe aktardığınız "ağaç sallama" uygulamalarına izin veren modern JavaScript Modülü biçimini benimser. Uygulamanıza bağlı olarak, modüler SDK ile ağaç sallama, ad alanlı API kullanılarak oluşturulan benzer bir uygulamaya göre %80 daha az kilobaytla sonuçlanabilir.
  • Modüler SDK, devam eden özellik geliştirmeden yararlanmaya devam ederken, ad alanlı API bundan yararlanmayacaktır.