Ad alanına sahip API'den modüler API'ye yükseltme

compat kitaplıklarından sürüm 8 veya önceki sürümlere kadar herhangi bir ad alanına sahip Firebase Web API'sini kullanan uygulamalar, bu kılavuzdaki talimatları kullanarak modüler API'ye geçiş yapabilir.

Bu kılavuzda, ad alanına sahip API hakkında bilgi sahibi olduğunuz ve yükseltme ve devam eden modüler uygulama geliştirme işlemi için webpack veya Rollup gibi bir modül paketleyiciden yararlanacağınız varsayılır.

Geliştirme ortamınızda bir modül paketleyici kullanmanız kesinlikle önerilir. API kullanmıyorsanız modüler API'nin küçültülmüş uygulama boyutuyla ilgili temel avantajlarından yararlanamazsınız. SDK'yı yüklemek için npm veya yarn değerine ihtiyacınız vardır.

Bu kılavuzdaki yeni sürüme geçirme adımları, Authentication ve Cloud Firestore SDK'larını kullanan hayali bir web uygulamasına dayalı olacaktır. Örneklerin üzerinden geçerek desteklenen tüm Firebase Web SDK'larını yeni sürüme geçirmek için gereken kavramlar ve pratik adımlar konusunda uzmanlaşabilirsiniz.

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

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

  • Modüler: Web uygulamanızı mümkün olduğunca küçük ve hızlı hale getirmek için ağaç sallamayı (kullanılmayan kodların kaldırılmasını) kolaylaştırmak üzere tasarlanmış yeni bir API yüzeyidir.
  • Ad Aralıklı (compat) - SDK'nın önceki sürümleriyle tamamen uyumlu olan ve Firebase kodunuzun tamamını tek seferde değiştirmeden yükseltmenize olanak tanıyan, tanıdık bir API yüzeyidir. Uyumlu kitaplıkların, ad alanına sahip eşdeğerlerine göre çok az boyutu veya performans avantajı vardır ya da hiç yoktur.

Bu kılavuzda, yükseltmenizi kolaylaştırmak için uyumlu kitaplıklardan yararlanacağınız varsayılmıştır. Bu kitaplıklar, modüler API için yeniden düzenlenen kodla birlikte ad alanına sahip kodu kullanmaya devam etmenize olanak tanır. Bu sayede, yükseltme sürecinde çalışırken uygulamanızı daha kolay derleyebilir ve hata ayıklayabilirsiniz.

Firebase Web SDK'ya çok az maruz kalan uygulamalar (ör. Authentication API'lerine yalnızca basit bir çağrı yapan uygulamalar) için eski ad alanı kodları, uyumlu kitaplıkları kullanmadan yeniden düzenlemeye uygun olabilir. Bu tür bir uygulamayı yeni sürüme geçiriyorsanız uyumlu kitaplıkları kullanmadan bu kılavuzdaki "modüler API" ile ilgili talimatları uygulayabilirsiniz.

Yükseltme işlemi hakkında

Yükseltme işleminin her adımının kapsamı belirlenir. Böylece uygulamanızın kaynağını düzenlemeyi bitirebilir ve ardından kesintisiz bir şekilde derleyip çalıştırabilirsiniz. Özetle, bir uygulamayı yeni sürüme geçirmek için yapmanız gerekenler şunlardır:

  1. Uygulamanıza modüler kitaplıkları ve uyumluluk kitaplıklarını ekleyin.
  2. Uyumlu hale getirmek için kodunuzdaki içe aktarma ifadelerini güncelleyin.
  3. Tek bir ürünün (örneğin, Kimlik Doğrulaması) kodunu modüler stile yeniden düzenleyin.
  4. İsteğe bağlı: Devam etmeden önce, Authentication'ın uygulama boyutu avantajından yararlanmak için bu noktada Authentication'a yönelik
  5. Her ürün için işlevleri (örneğin, Cloud Firestore, FCM vb.) 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. Kalan tüm uyumlu ifadeleri ve kodu uygulamanızdan kaldırın.

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

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

npm i firebase@10.12.2

# OR

yarn add firebase@10.12.2

İthalatları uyumlu bir şekilde güncelleyin

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

Önce: 8. veya önceki sürümler

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

Sonra: karşılaştırma

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

Modüler stili yeniden düzenleyin

Ad alanına sahip API'ler nokta zincirli ad alanına ve hizmet kalıbına dayansa da modüler yaklaşım, kodunuzun temel olarak işlevler etrafında düzenleneceğ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 işlemi döndürmez. Bunun yerine, paketler bağımsız işlevleri dışa aktarır.

Modüler API'de hizmetler ilk bağımsız değişken olarak iletilir ve işlev, geri kalanını gerçekleştirmek için hizmetin ayrıntılarını kullanır. Şimdi, Authentication ve Cloud Firestore API'lerine yapılan çağrıları yeniden düzenleyen iki örnekte, bunun nasıl çalıştığını inceleyelim.

1. Örnek: Kimlik doğrulama işlevini yeniden düzenleme

Önce: Karşılaştırma

Uyumlu kod, ad alanı kodu ile aynıdır ancak içe aktarma işlemleri 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 öğesini alır. onAuthStateChanged işlevi, ad alanına sahip 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
});

getRedirectResult Auth yönteminin işlenmesini güncelleyin

Modüler API, getRedirectResult ürününde zarar veren bir değişiklik yaratıyor. Yönlendirme işlemi çağrılmadığında modüler API, null kullanıcısıyla UserCredential döndüren ad alanına sahip API'nin aksine null döndürür.

Önce: Karşılaştırma

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;

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

Önce: Karşılaştırma

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 öğesini ilk parametre olarak alır. Bu parametre, önceki bir örnekte initializeApp parametresinden döndürülür. Sorgu oluşturma kodunun modüler API'de çok farklı olduğuna dikkat edin. Zincirleme yoktur ve query ya da where gibi yöntemler artık serbest fonksiyon olarak kullanıma sunulmuştur.

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ştirilmesine neden olan bir zarar değişikliğine neden olur. İşlevsellik temelde aynıdır (dokümanın var olup olmadığını test eder), ancak aşağıda gösterildiği gibi yeni yöntemi kullanmak için kodunuzu yeniden düzenlemeniz gerekir:

Before:compat

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

Sonra: modüler

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

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

Yükseltme sırasında uyumlu kitaplıklar sayesinde, modüler API için yeniden düzenlenen kodla birlikte ad alanına sahip kodu kullanmaya devam edebilirsiniz. Bu sayede, Authentication veya diğer Firebase SDK kodlarını modüler stilde yeniden düzenlerken Cloud Firestore için mevcut ad alanı kodu koruyabilir ve uygulamanızı her iki kod stiliyle de başarılı bir şekilde derleyebilirsiniz. Aynı durum Cloud Firestore gibi bir ürünün içindeki ad alanına sahip ve modüler API kodu için de geçerlidir. Uyumlu paketleri içe aktardığınız sürece yeni ve eski kod stilleri birlikte kullanılabilir:

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 uyumlu ifadeleri ve kodu uygulamanızdan tamamen kaldırmadığınız sürece modüler kodun uygulama boyutu avantajlarından yararlanamayacağınızı unutmayın.

Başlatma kodunu güncelleme

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

Önce: Karşılaştırma

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ı anlamak için sonuçta tüm çağrıları yukarıda gösterilen modüler stile dönüştürmeniz ve tüm import "firebase/compat/* ifadelerini kodunuzdan kaldırmanız gerekir. İşiniz bittiğinde artık firebase.* genel ad alanına veya ad alanına sahip API stilindeki başka herhangi bir koda referans bulunmamalıdır.

Pencereden uyumluluk kitaplığını 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ı kullanılarak Firebase'in yüklenmesine ve yönetilmesine olanak tanıyordu. Kullanılmayan kodların kaldırılmasına izin vermediği için bu işlem gelecekte önerilmez. Bununla birlikte, JavaScript SDK'sının uyumlu sürümü, modüler yükseltme yoluna hemen başlamamayı tercih eden geliştiriciler için window ile çalışır.

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

Uyumluluk kitaplığı, gelişmiş modüler kodu kullanır ve bu API'ye ad alanı API'siyle aynı API'yi sunar. Bu sayede, ayrıntılar için ad aralıklı API referansına ve ad alanlı kod snippet'lerine bakabilirsiniz. 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 önerilmez.

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

Tamamen modüler hale getirilmiş SDK, önceki sürümlere kıyasla şu avantajlara sahiptir:

  • Modüler SDK, uygulama boyutunu önemli ölçüde küçültür. Modern JavaScript Modülü biçimini kullanır ve yalnızca uygulamanızın ihtiyaç duyduğu yapıları içe aktardığınız "ağaç sallama" uygulamalarına olanak tanır. Uygulamanıza bağlı olarak, modüler SDK ile ağaç sallama, ad alanına sahip API kullanılarak oluşturulan benzer bir uygulamadan% 80 daha az kilobayt almanıza neden olabilir.
  • Modüler SDK, devam eden özellik geliştirmeden yararlanmaya devam ederken ad alanı olan API bunu yapmayacaktır.