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

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

Bu kılavuzda, ad alanına sahip API'yi bildiğinizi ve yükseltme ve devam eden modüler uygulama geliştirme için webpack veya Rollup gibi bir modül paketleyiciden yararlanacağınız varsayılmaktadır.

Geliştirme ortamınızda modül birleştirme aracı kullanmanızı önemle tavsiye ederiz. Bu tür bir araç kullanmıyorsanız modüler API'nin uygulama boyutunu azaltma konusundaki başlıca avantajlarından yararlanamazsınız. SDK'yı yüklemek için npm veya yarn kullanmanız gerekir.

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

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 kodun kaldırılması) kolaylaştırmak üzere tasarlanmış yeni bir API yüzeyi.
  • Ad alanı (compat): SDK'nın önceki sürümleriyle tam uyumlu olan, 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ı adlarına sahip benzerlerine kıyasla boyut veya performans avantajları yoktur.

Bu rehberde, 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 yapılandırılmış kodla birlikte ad alanlı kodu kullanmaya devam etmenize olanak tanır. Bu sayede, yükseltme sürecinde çalışırken uygulamanızı daha kolay derleyebilir ve hata ayıklama yapabilirsiniz.

Firebase Web SDK'sına çok az maruz kalan uygulamalarda (ör. yalnızca Authentication API'lerini basit bir şekilde çağıran bir uygulama) uyumluluk kitaplıklarını kullanmadan eski ad alanlı kodu yeniden yapılandırmak yararlı olabilir. Bu tür bir uygulamayı yükseltiyorsanız uyumluluk kitaplıklarını kullanmadan bu kılavuzda "modüler API" için verilen talimatları uygulayabilirsiniz.

Yükseltme süreci hakkında

Yükseltme sürecinin her adımı, uygulamanızın kaynağını düzenlemeyi bitirip derleyip kesinti olmadan çalıştırabilmeniz için kapsamlandırılmıştır. Özetlemek gerekirse, bir uygulamayı yükseltmek için yapmanız gerekenler şunlardır:

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

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

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

npm i firebase@11.3.0

# OR

yarn add firebase@11.3.0

İçe aktarma işlemlerini uyumlu olarak 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:

Önceki: 8 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 göre yeniden yapılandırın

Ad alanı içeren API'ler noktayla zincirlenmiş 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 işlemi döndürmez. Bunun yerine paketler işlevleri tek tek dışa aktarır.

Modüler API'de hizmetler ilk bağımsız değişken olarak iletilir ve işlev, geri kalanını yapmak için hizmetin ayrıntılarını kullanır. Bunun işleyiş şeklini, Authentication ve Cloud Firestore API'lerine yapılan çağrıları yeniden düzenleyen iki örnekte inceleyelim.

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

Önce: compat

Uyumlu kod, ad alanlı 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 parametresi olarak firebaseApp değerini alır. onAuthStateChanged işlevi, ad alanı içeren API'de olduğu gibi auth örneğinden zincirlenmez. Bunun yerine, ilk parametresi auth olan 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şlenmesi güncellendi

Modüler API, getRedirectResult sürümünde önemli bir değişiklik yapıyor. Yönlendirme işlemi çağrılmadığında modüler API, null kullanıcısı olan bir UserCredential döndüren ad alanı API'sinin aksine 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 parametresi olarak firebaseApp değerini alır. Bu değer, önceki bir örnekte initializeApp işlevinden döndürülmüştür. Sorgu oluşturmak için kullanılan kodun modüler API'de çok farklı olduğunu unutmayın. Zincirleme yoktur ve query veya where gibi yöntemler artık serbest 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

Modüler API, firestore.DocumentSnapshot.exists mülkünün yöntem olarak değiştirildiği önemli bir değişiklik sunar. İşlevsellik temelde aynıdır (bir dokümanın var olup olmadığını test etme) ancak kodunuzu, gösterildiği gibi 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 alanına sahip ve modüler kod stillerini birleştirme

Yükseltme sırasında uyumluluk kitaplıklarını kullanmak, modüler API için yeniden yapılandırılmış kodun yanı sıra ad alanlı kodu kullanmaya devam etmenizi sağlar. Yani Authentication veya diğer Firebase SDK kodlarını modüler stile yeniden düzenlerken Cloud Firestore için mevcut ad alanlı kodu saklayabilir ve uygulamanızı her iki kod stiliyle de başarıyla derleyebilirsiniz. Aynı durum, Cloud Firestore gibi bir üründeki adı alana sahip 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 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 beyanları ve kodunu uygulamanızdan tamamen kaldırana kadar modüler kodun uygulama boyutu 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 dizimi kullanacak şekilde güncelleyin. Bu kodu, uygulamanızdaki tüm kodu yeniden yapılandırmayı 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'ler için 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 tüm çağrıları yukarıda gösterilen modüler stile dönüştürmeli ve import "firebase/compat/* ifadelerinin tümünü kodunuzdan kaldırmalısınız. İşlemi tamamladığınızda, firebase.* küresel ad alanına veya ad alanı adlandırmalı API stilindeki başka bir koda artık referans olmamalı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 izin veriyordu. Kullanılmayan kodun kaldırılmasına izin vermediği için bu yöntemin artık kullanılması önerilmez. Ancak JavaScript SDK'sının uyumlu sürümü, modüler yükseltme yoluna hemen başlamayı tercih etmeyen geliştiriciler için window ile çalışır.

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

Uyumluluk kitaplığı, modüler kod kullanır ve bu koda, ad alanına sahip API ile aynı API'yi sağlar. Yani ayrıntılar için ad alanına sahip API referansına ve ad alanına sahip kod snippet'lerine bakabilirsiniz. Bu yöntem uzun süreli kullanım için önerilmez ancak tamamen modüler kitaplığa geçiş için başlangıç olarak kullanılabilir.

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

Tamamen modülerleştirilmiş SDK, önceki sürümlere kıyasla aşağıdaki avantajlara sahiptir:

  • Modüler SDK, uygulama boyutunun önemli ölçüde azaltılmasını sağlar. Modern JavaScript modülü biçimini benimser 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 işlemi, ad alanı tanımlanmış API kullanılarak oluşturulan benzer bir uygulamaya kıyasla% 80 daha az kilobaytlık bir boyuta neden olabilir.
  • Modüler SDK, devam eden özellik geliştirmelerinden yararlanmaya devam edecek ancak ad alanı adı verilen API bu durumdan yararlanamayacaktır.