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

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

Bu kılavuzda, namespaced 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ılmaktadır.

Geliştirme ortamınızda bir modül paketleyici kullanmanız önemle tavsiye edilir. Modül paketleyici 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 gerekir.

Bu kılavuzdaki yükseltme adımları, Authentication ve Cloud Firestore SDK'larını kullanan hayali bir web uygulamasına dayanmaktadı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 tree-shaking (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 olan ve tüm Firebase kodunuzu tek seferde değiştirmeden yükseltme yapmanıza olanak tanıyan tanıdık bir API yüzeyi. Uyumluluk kitaplıklarının, ad alanlı benzerlerine kıyasla boyut veya performans açısından çok az avantajı vardır ya da hiç yoktur.

Bu kılavuzda, yükseltme işleminizi kolaylaştırmak için uyumluluk kitaplıklarından yararlanacağınız varsayılmaktadır. Bu kitaplıklar, ad alanlı kodu modüler API için yeniden düzenlenmiş kodla birlikte kullanmaya devam etmenize olanak tanır. Bu sayede, yükseltme sürecinde uygulamanızı daha kolay derleyebilir ve hatalarını ayıklayabilirsiniz.

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

Firebase web SDK'sına çok az maruz kalan uygulamalarda (ör. Authentication 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. Bu tür bir uygulamayı yükseltiyorsanız uyumluluk kitaplıklarını kullanmadan "modüler API" için 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 tamamlayıp ardından kesinti olmadan derleyip çalıştırabileceğiniz şekilde kapsamlandırılmıştır. Özetlemek gerekirse, 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 olarak güncelleyin.
3. Tek bir ürünün (ör. Authentication) kodunu modüler stile göre yeniden düzenleyin.
4. İsteğe bağlı: Bu noktada, devam etmeden önce Authentication için uygulama boyutu avantajından yararlanmak amacıyla Authentication uyumluluk kitaplığını ve Authentication için uyumluluk kodunu kaldırın.
5. Her ürün için işlevleri (ör. Cloud Firestore, FCM vb.) modüler stile göre yeniden düzenleyin, tüm alanlar tamamlanana kadar derleyin ve test edin.
6. Başlatma kodunu modüler stile güncelleyin.
7. Kalan tüm uyumluluk ifadelerini ve uyumluluk kodunu uygulamanızdan kaldırın.

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

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

npm i firebase@13.2.0

# OR

yarn add firebase@13.2.0

İçe aktarmaları uyumlu olacak şekilde 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 "compat" sürümünü kullanacak şekilde değiştirin. Örneğin:

Önceki: 8 veya daha eski bir sürüm

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 göre yeniden düzenleme

Ad alanlı API'ler, nokta zincirli bir ad alanı ve hizmet kalıbını temel alırken 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, ayrı 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 işlemleri yapmak için hizmetin ayrıntılarını kullanır. Authentication ve Cloud Firestore API'lerine yapılan çağrıları yeniden düzenleyen iki örnekle bunun nasıl çalıştığını inceleyelim.

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

Önce: compat

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

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

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

getRedirectResult kimlik doğrulama yönteminin işlenmesini güncelleme

Dikkat: Uygulamanız getRedirectResult kimlik doğrulama yöntemini kullanıyorsa bu bölümde açıklanan güncellemeleri yapmanız gerekir. Kodunuzu yeniden düzenlemezseniz uygulamanızda öngörülemeyen davranışlar görülebilir.

Modüler API, getRedirectResult sürümünde zarar veren bir değişiklik getirir. Yönlendirme işlemi çağrılmadığında, namespaced API'nin aksine modular API null döndürür. Namespaced API ise null kullanıcısı olan bir UserCredential döndürürdü.

Ö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 tarafından döndürülmüştü. Modüler API'de sorgu oluşturma kodunun çok farklı olduğuna dikkat edin. Zincirleme yoktur ve query veya where gibi yöntemler artık serbest 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üncelleme

Dikkat: Uygulamanız DocumentSnapshot.exists özelliğini kullanıyorsa bu bölümde açıklanan güncellemeyi yapmanız gerekir. Kodunuzu yeniden düzenlemezseniz uygulamanızda öngörülemeyen davranışlar görülebilir.

Modüler API, firestore.DocumentSnapshot.exists özelliğinin bir yöntem olarak değiştirildiği zarar veren bir değişiklik sunar. İşlevler temelde aynıdır (bir dokümanın mevcut olup olmadığını test etme) ancak kodunuzu, gösterildiği gibi daha yeni yöntemi kullanacak şekilde 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 alanlı ve modüler kod stillerini birleştirme

Yükseltme sırasında compat kitaplıklarını kullanmak, ad alanlı kodu modüler API için yeniden düzenlenmiş kodla birlikte kullanmaya devam etmenize olanak tanır. Bu sayede, Authentication veya diğer Firebase SDK'sı kodunu modüler stile göre yeniden düzenlerken Cloud Firestore için mevcut ad alanlı kodu koruyabilir ve uygulamanızı her iki kod stiliyle de başarıyla derleyebilirsiniz. Aynı durum, bir ürün içindeki ad alanlı ve modüler API kodu için de geçerlidir (ör. Cloud Firestore). 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 derlense de uyumluluk ifadelerini ve kodunu uygulamanızdan tamamen kaldırana kadar 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. Bu kodu, uygulamanızdaki tüm kodları yeniden düzenlemeyi tamamladıktan sonra güncellemeniz önemlidir. Bunun nedeni, firebase.initializeApp() işlevinin hem uyumlu hem de modüler API'ler için genel durumu başlatması, modüler initializeApp() işlevinin ise yalnızca modüler API'nin durumunu 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ır

Modüler API'nin boyut avantajlarından yararlanmak için tüm çağrıları yukarıda gösterilen modüler stile dönüştürmeniz ve kodunuzdaki tüm import "firebase/compat/* ifadelerini kaldırmanız gerekir. İşlemi tamamladığınızda firebase.* global ad alanına veya namespaced API stilindeki başka bir koda referans kalmamalı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ını kullanarak Firebase'in yüklenmesine ve yönetilmesine olanak tanıyordu. Kullanılmayan kodların kaldırılmasına izin vermediği için bu yöntemin kullanılması önerilmez. Ancak JavaScript SDK'nın uyumlu sürümü, modüler yükseltme yolunu hemen kullanmaya başlamayı tercih etmeyen geliştiriciler için window ile çalışır.

<script src="https://www.gstatic.com/firebasejs/13.2.0/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/13.2.0/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/13.2.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 bu kodu namespaced API ile aynı API ile sağlar. Bu, ayrıntılar için namespaced API referansına ve namespaced 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 geçiş için bir başlangıç olarak 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 boyutunu önemli ölçüde azaltır. Modern JavaScript modül biçimini benimser ve yalnızca uygulamanızın ihtiyaç duyduğu yapıları içe aktardığınız "tree shaking" uygulamalarına olanak tanır. Uygulamanıza bağlı olarak, modüler SDK ile ağaç sallama, namespaced API kullanılarak oluşturulan benzer bir uygulamaya göre %80 daha az kilobayt ile sonuçlanabilir.
• Modüler SDK, devam eden özellik geliştirmelerinden yararlanmaya devam edecek ancak namespaced API bu geliştirmelerden yararlanamayacak.