Ad alanı adı verilen API'den modüler uygulamaya geçiş

compat kitaplıklarından 8. sürüm veya daha önceki sürümlere kadar ad alanı içeren herhangi bir Firebase web API'sini kullanan uygulamalar, bu kılavuzdaki talimatları kullanarak modüler API'ye geçmeyi düşünmelidir.

Bu kılavuzda, ad alanlı API'yi bildiğiniz ve yükseltme ile devam eden modüler uygulama geliştirme için webpack veya Rollup gibi bir modül paketleyici kullanacağınız varsayılır.

Geliştirme ortamınızda bir modül paketleyici kullanmanız önemle tavsiye edilir. Bunlardan birini kullanmazsanız modüler API'nin uygulama boyutunu küçültme gibi temel avantajlarından yararlanamazsınız. SDK'yı yüklemek için npm veya yarn'a ihtiyacınız vardır.

Bu kılavuzdaki yükseltme adımları, Authentication ve Cloud Firestore SDK'larını kullanan hayali bir web uygulamasına göre açıklanacaktır. Örnekleri inceleyerek, desteklenen tüm Firebase web SDK'larını yükseltmek için gereken kavramları ve pratik adımları öğrenebilirsiniz.

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

Firebase web SDK'sı için iki tür kitaplık mevcuttur:

• Modüler: Web uygulamanızı mümkün olduğunca küçük ve hızlı hale getirmek için ağaç sallama (kullanılmayan kodun kaldırılması) işlemini kolaylaştırmak üzere tasarlanmış yeni bir API yüzeyi.
• Ad alanlı (compat): SDK'nın önceki sürümleriyle tamamen uyumlu, tanıdık bir API yüzeyidir. Firebase kodunuzun tamamını aynı anda değiştirmeden yükseltme yapmanıza olanak tanır. Uyumluluk kitaplıklarının, ad alanı içeren karşılıklarına kıyasla boyut veya performans açısından çok az avantajı vardır ya da hiç avantajı yoktur.

Bu kılavuzda, yükseltme işlemini kolaylaştırmak için uyumluluk kitaplıklarından yararlanacağınız varsayılmaktadır. Bu kitaplıklar, modüler API için yeniden düzenlenmiş kodun yanı sıra ad alanı içeren kodu kullanmaya devam etmenize olanak tanır. Bu sayede, yükseltme sürecinde çalışırken uygulamanızı daha kolay derleyip hatalarını ayıklayabilirsiniz.

Unutmayın: Uyumluluk kitaplıkları geçici bir çözümdür ve gelecekteki bir ana SDK sürümünde (ör. 10 veya 11) tamamen kaldırılacaktır. Nihai hedefiniz, uyumluluk kodunu kaldırmak ve uygulamanızda yalnızca modüler tarzda kod bulundurmaktır.

Firebase web SDK'sına çok az maruz kalan uygulamalar (ör. yalnızca Authentication API'lerine basit bir çağrı yapan bir uygulama) için, 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" ile ilgili bu kılavuzdaki talimatları uygulayabilirsiniz.

Yükseltme süreci hakkında

Yükseltme sürecinin her adımı, uygulamanızın kaynağını düzenlemeyi bitirip derleyip çalıştırabilmeniz için kapsamlı bir şekilde ele alınır. Özetle, bir uygulamayı yükseltmek için yapmanız gerekenler şunlardır:

1. Modüler kitaplıkları ve uyumluluk kitaplıklarını uygulamanıza ekleyin.
2. Kodunuzdaki içe aktarma ifadelerini compat. ile güncelleyin.
3. Tek bir ürün için kodu (örneğin, Authentication) modüler stile göre yeniden düzenleyin.
4. İsteğe bağlı: Devam etmeden önce Authentication için uygulama boyutu avantajını elde etmek amacıyla bu noktada Authentication uyumluluk kitaplığını ve Authentication uyumluluk kodunu kaldırın.
5. Her ürünün (ör. Cloud Firestore, FCM vb.) işlevlerini modüler stile göre yeniden düzenleyin, tüm alanlar tamamlanana kadar derleyin ve test edin.
6. İlk kullanıma hazırlama kodunu modüler stile güncelleyin.
7. Uygulamanızdaki kalan tüm uyumluluk ifadelerini ve uyumluluk kodunu kaldırın.

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

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

npm i firebase@12.6.0

# OR

yarn add firebase@12.6.0

İçe aktarma işlemlerini uyumlu hale getirmek için güncelleme

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 "compat" sürümünü kullanacak şekilde değiştirin. Örneğin:

Önce: 8. sürüm veya daha eski sürümler

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

Sonra: compat

// 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 modeline dayalı olsa 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 döndürmez. Bunun yerine, paketler ayrı işlevleri dışa aktarır.

Modüler API'de hizmetler ilk bağımsız değişken olarak iletilir ve işlev daha sonra geri kalan işlemleri yapmak 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 bu işlemin nasıl çalıştığını inceleyelim.

1. örnek: Authentication işlevini yeniden düzenleme

Önce: compat

Uyumluluk kodu, 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 parametre olarak firebaseApp değerini alır. onAuthStateChanged işlevi, ad alanlı API'de olduğu gibi auth örneğinden zincirlenmez. Bunun yerine, auth öğesini ilk parametre olarak alan ücretsiz bir işlevdir.

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

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

Kimlik doğrulama yönteminin işlenmesiyle ilgili güncellemeler getRedirectResult

Dikkat: Uygulamanızda kimlik doğrulama yöntemi getRedirectResult kullanılıyorsa bu bölümde açıklanan güncellemeleri yapmanız gerekir. Kodunuzu yeniden düzenlememeniz uygulamanın beklenmedik şekilde çalışmasına neden olabilir.

Modüler API, getRedirectResult içinde önemli bir değişiklik sunuyor. Yönlendirme işlemi çağrılmadığında, ad alanlı API'nin null kullanıcısıyla birlikte UserCredential döndürmesinin aksine, modüler API null döndürür.

Önce: compat

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

Sonra: modüler

getFirestore işlevi, ilk parametre olarak firebaseApp değerini alır. Bu değer, önceki bir örnekte initializeApp işlevinden döndürülmüştü. Sorgu oluşturma kodunun modüler API'de çok farklı olduğunu unutmayın. Zincirleme yoktur ve query veya where gibi yöntemler artık ücretsiz işlevler olarak sunulmaktadır.

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'a yapılan referansları güncelleme DocumentSnapshot.exists

Dikkat: Uygulamanız DocumentSnapshot.exists özelliğini kullanıyorsa bu bölümde açıklanan güncellemeyi yapmanız gerekir. Kodunuzu yeniden düzenlememeniz uygulamanın beklenmedik şekilde çalışmasına neden olabilir.

Modüler API, firestore.DocumentSnapshot.exists özelliğinin yöntem olarak değiştirildiği, uyumluluğu bozan bir değişiklik sunuyor. İşlevsellik temelde aynıdır (bir belgenin var olup olmadığını test etme). Ancak kodunuzu, gösterildiği gibi daha yeni yöntemi kullanacak şekilde yeniden düzenlemeniz gerekir:

Önce:compat

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

Sonra: modüler

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

3. örnek: Ad alanlı ve modüler kod stillerini birleştirme

Yükseltme sırasında uyumluluk kitaplıklarını kullanmak, ad alanı içeren kodu modüler API için yeniden düzenlenmiş kodla birlikte kullanmaya devam etmenizi sağlar. Bu sayede, Cloud Firestore için mevcut ad alanlı kodu koruyabilir, Authentication veya diğer Firebase SDK kodunu modüler stile yeniden düzenlerken uygulamanızı her iki kod stiliyle de başarıyla derleyebilirsiniz. Aynı durum, Cloud Firestore gibi bir ürün içindeki ad alanı oluşturulmuş ve modüler API kodu için de geçerlidir. Uyumluluk paketlerini 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 uyumluluk ifadelerini ve kodu uygulamanızdan tamamen kaldırmadığınız sürece modüler kodun uygulama boyutuyla ilgili avantajlarından yararlanamayacağınızı unutmayın.

İlk kullanıma hazırlama kodunu güncelleme

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

Önce: compat

import firebase from "firebase/compat/app"

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

Sonra: modüler

import { initializeApp } from "firebase/app"

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

Uyumluluk kodunu kaldırma

Modüler API'nin boyut avantajlarından yararlanmak için sonunda tüm çağrıları yukarıda gösterilen modüler stile dönüştürmeli ve kodunuzdaki tüm import "firebase/compat/* ifadelerini kaldırmalısınız. İşlemi tamamladığınızda, firebase.* genel ad alanına veya ad alanlı API stilindeki başka bir koda artık referans verilmemelidir.

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ümlerinde, window.firebase ad alanı kullanılarak Firebase'in yüklenmesine ve yönetilmesine izin veriliyordu. Bu yöntem, kullanılmayan kodların kaldırılmasına izin vermediği için artık önerilmemektedir. Ancak JavaScript SDK'sının uyumluluk sürümü, window için çalışır. Bu sürüm, modüler yükseltme yoluna hemen başlamayı tercih etmeyen geliştiriciler için uygundur.

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

Uyumluluk kitaplığı, arka planda modüler kod kullanır ve bunu ad alanlı API ile aynı API ile sağlar. Bu, ayrıntılar için ad alanlı API referansına ve ad alanlı kod snippet'lerine başvurabileceğiniz anlamına gelir. Bu yöntem, uzun süreli kullanım için önerilmez ancak tamamen modüler kitaplığa yükseltmeye başlamak için kullanılabilir.

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

Tamamen modüler hale getirilmiş SDK'nın önceki sürümlere göre şu avantajları vardır:

• Modüler SDK, uygulama boyutunun önemli ölçüde küçülmesini sağlar. Modern JavaScript modülü biçimini kullanır. Bu sayede, uygulamanızın ihtiyaç duyduğu yapay nesneleri içe aktardığınız "tree shaking" uygulamalarına olanak tanır. Uygulamanıza bağlı olarak, modüler SDK ile tree-shaking, ad alanlı API kullanılarak oluşturulan benzer bir uygulamaya kıyasla% 80 daha az kilobayt ile sonuçlanabilir.
• Modüler SDK, devam eden özellik geliştirmelerinden yararlanmaya devam edecek ancak ad alanı içeren API yararlanamayacak.