SSR (Sunucu Tarafında Oluşturma) ile dinamik web uygulamalarında Firebase'i kullanma

Firebase JS SDK'sı veya diğer Firebase istemci SDK'larıyla çalıştıysanız FirebaseApp arayüzüne ve uygulama örneklerini yapılandırmak için bu arayüzün nasıl kullanılacağına muhtemelen aşinasınızdır. Sunucu tarafında benzer işlemleri kolaylaştırmak için Firebase, FirebaseServerApp sunar.

FirebaseServerApp, sunucu tarafında oluşturma (SSR) ortamlarında kullanılmak üzere FirebaseApp'nin bir varyantıdır. İstemci taraflı oluşturma (CSR) ve sunucu taraflı oluşturma arasındaki ayrımı kapsayan Firebase oturumlarını devam ettirmek için araçlar içerir. Bu araçlar ve stratejiler, Firebase ile oluşturulan ve Firebase App Hosting gibi Google ortamlarında dağıtılan dinamik web uygulamalarını iyileştirmeye yardımcı olabilir.

FirebaseServerApp ile yapabilecekleriniz:

  • Tam yönetim haklarına sahip Firebase Admin SDK'nın aksine, sunucu tarafı kodunu kullanıcı bağlamında yürütün.
  • SSR ortamlarında Uygulama Kontrolü'nün kullanımını etkinleştirin.
  • İstemcide oluşturulan bir Firebase Auth oturumunu devam ettirme

FirebaseServerApp yaşam döngüsü

Sunucu tarafı oluşturma (SSR) çerçeveleri ve bulut çalışanları gibi tarayıcı dışı diğer çalışma zamanları, birden fazla yürütme işleminde kaynakları yeniden kullanarak başlatma süresini optimize eder. FirebaseServerApp, referans sayısı mekanizması kullanarak bu ortamlara uyum sağlayacak şekilde tasarlanmıştır. Bir uygulama, önceki bir initializeServerApp ile aynı parametrelerle initializeServerApp çağırırsa önceden başlatılmış olan aynı FirebaseServerApp örneğini alır. Bu sayede gereksiz başlatma yükü ve bellek ayırma işlemleri azaltılır. deleteApp, bir FirebaseServerApp örneğinde çağrıldığında referans sayısını azaltır ve referans sayısı sıfıra ulaştıktan sonra örnek serbest bırakılır.

FirebaseServerApp örnek temizleniyor

Özellikle paralel olarak birçok eşzamansız işlem çalıştırıyorsanız bir FirebaseServerApp örneğinde deleteApp yöntemini ne zaman çağıracağınızı bilmek zor olabilir. FirebaseServerAppSettings öğesinin releaseOnDeref alanı bu işlemi basitleştirmeye yardımcı olur. releaseOnDeref öğesini, isteğin kapsamının kullanım ömrüne sahip bir nesneye (ör. SSR isteğinin başlık nesnesi) referans olarak atarsanız çerçeve, başlık nesnesini geri aldığında FirebaseServerApp referans sayısını azaltır. Bu işlem, FirebaseServerApp örneğinizi otomatik olarak temizler.

releaseOnDeref için örnek bir kullanım:

/// Next.js
import { headers } from 'next/headers'
import { FirebaseServerAppSettings, initializeServerApp} from "firebase/app";

export default async function Page() {
  const headersObj = await headers();
  let appSettings: FirebaseServerAppSettings = {};
  appSettings.releaseOnDeref = headersObj;
  const serverApp = initializeServerApp(firebaseConfig, appSettings);
  ...
}

İstemcide oluşturulan kimliği doğrulanmış oturumları devam ettirme

FirebaseServerApp örneği bir Auth kimlik jetonuyla başlatıldığında istemci tarafı oluşturma (CSR) ve sunucu tarafı oluşturma (SSR) ortamları arasında kimliği doğrulanmış kullanıcı oturumlarının köprülenmesini sağlar. Auth kimlik jetonu içeren bir FirebaseServerApp nesnesiyle başlatılan Firebase Auth SDK'sı örnekleri, uygulamanın herhangi bir oturum açma yöntemi çağırmasına gerek kalmadan başlatma sırasında kullanıcının oturumunu açmaya çalışır.

Auth kimlik jetonu sağlandığında uygulamalar, istemcide Auth'un oturum açma yöntemlerinden herhangi birini kullanabilir. Böylece, kullanıcı etkileşimi gerektiren oturum açma yöntemlerinde bile oturumun sunucu tarafında devam etmesi sağlanır. Ayrıca, kimliği doğrulanmış Firestore sorguları gibi yoğun işlemlerin sunucuya yüklenmesini sağlayarak uygulamanızın oluşturma performansını artırır.

/// Next.js
import { initializeServerApp } from "firebase/app";
import { getAuth } from "firebase/auth";

// Replace the following with your app's
// Firebase project configuration
const firebaseConfig = {
  // ...
};

const firebaseServerAppSettings = {
  authIdToken: token  // See "Pass client tokens to the server side
                      // rendering phase" for an example on how transmit
                      // the token from the client and the server.
}

const serverApp =
  initializeServerApp(firebaseConfig,
                      firebaseServerAppSettings);
const serverAuth = getAuth(serverApp);

// FirebaseServerApp and Auth will now attempt
// to sign in the current user based on provided
// authIdToken.

SSR ortamlarında Uygulama Kontrolü'nü kullanma

Uygulama Kontrolü yaptırımı, Firebase SDK'larının getToken yöntemini dahili olarak çağırmak için kullandığı bir Uygulama Kontrolü SDK'sı örneğine dayanır. Oluşturulan jeton, tüm Firebase hizmetlerine gönderilen isteklere eklenir ve arka ucun uygulamayı doğrulamasını sağlar.

Ancak Uygulama Kontrolü SDK'sı, uygulama doğrulaması için belirli sezgisel yöntemlere erişmek üzere bir tarayıcıya ihtiyaç duyduğundan sunucu ortamlarında başlatılamaz.

FirebaseServerApp alternatif bir çözüm sunar. FirebaseServerApp başlatma sırasında istemci tarafından oluşturulan bir Uygulama Kontrolü jetonu sağlanırsa bu jeton, Firebase hizmetleri çağrılırken Firebase ürün SDK'ları tarafından kullanılır. Böylece Uygulama Kontrolü SDK'sı örneğine gerek kalmaz.

/// Next.js
import { initializeServerApp } from "firebase/app";

// Replace the following with your app's
// Firebase project configuration
const firebaseConfig = {
  // ...
};

const firebaseServerAppSettings = {
  appCheckToken: token // See "Pass client tokens to the server side
                       // rendering phase" for an example on how transmit
                       // the token from the client and the server.
}

const serverApp =
  initializeServerApp(firebaseConfig,
                      firebaseServerAppSettings);

// The App Check token will now be appended to all Firebase service requests.

İstemci jetonlarını sunucu tarafı oluşturma aşamasına iletme

Kimliği doğrulanmış Auth kimlik jetonlarını (ve Uygulama Kontrolü jetonlarını) istemciden sunucu tarafı oluşturma (SSR) aşamasına aktarmak için bir hizmet çalışanı kullanın. Bu yaklaşımda, SSR'yi tetikleyen getirme istekleri yakalanır ve jetonlar istek başlıklarına eklenir.

Firebase Auth hizmet çalışanının referans uygulaması için Hizmet çalışanlarıyla oturum yönetimi başlıklı makaleyi inceleyin. FirebaseServerApp başlatma işleminde kullanılmak üzere bu jetonların başlıklardan nasıl ayrıştırılacağını gösteren kod için Sunucu tarafı değişiklikleri bölümüne de bakın.

SSR ortamlarında Firestore'u kullanma

Sunucu tarafı oluşturma (SSR) ile web uygulamaları oluştururken performansı ve kullanıcı deneyimini optimize etmek için genellikle sunucu ile istemci arasında veri paylaşmanız gerekir. Firestore SDK'sı, sunucuda anlık görüntüleri ve belirli veri türlerini yakalayıp doğrudan istemci tarafı bileşenlerinize aktarmanıza olanak tanıyan serileştirme araçları sağlar. Bu işlem, istemcinin SSR aşamasında önceden getirilen verileri kullanarak durumu doldurmasını sağlayarak gereksiz getirme işlemlerini ortadan kaldırır. Ayrıca, bu serileştirilmiş durumlardan gerçek zamanlı dinleyicilere geçiş yaparak uygulamanızın veritabanıyla senkronize kalmasını sağlayabilirsiniz.

Bu bölümde, sunucu tarafı oluşturma (SSR) aşamasında alınan verilerin istemci tarafı bileşenlerde nasıl yeniden kullanılacağı açıklanmaktadır.

Veri Türlerini Serileştirme

Belirli Firestore veri türleri, verilerini serileştirilebilir bir biçime dönüştürmek için toJSON yöntemi sunar. Bunlar arasında Bytes, GeoPoint, Timestamp ve VectorValue gibi nesnelerin örnekleri yer alır.

Verileri JSON biçiminde aldıktan sonra, standart çerçeve mekanizmaları aracılığıyla veya bölüme yayılan bileşenlere parametre olarak sunucudan istemciye aktarabilirsiniz. Örneğin:

import {
  Bytes
} from 'firebase/firestore';

const BYTES_DATA = new Uint8Array([0, 1, 2, 3, 4, 5]);
const bytes = Bytes.fromUint8Array(BYTES_DATA);
const bytesJSON = bytes.toJSON();

Veri Türlerini Serileştirmeyi Kaldırma

Firestore veri türleri, serileştirilmiş verileri çalıştırılabilir bir Firestore veri türüne dönüştürmek için statik fromJSON yöntemini içerir.

Örneğin, aşağıdaki kod bir Bytes veri türünün serileştirmesini kaldırır:

import {
  Bytes
} from 'firebase/firestore';

// Assuming the same `bytesJSON` variable from the previous example.
const deserializedBytes = Bytes.fromJSON(bytesJSON);

Firestore anlık görüntülerini serileştirme ve serileştirmeyi kaldırma

Firestore veri türlerine benzer şekilde, toJSON kullanarak DocumentSnapshot ve QuerySnapshot örneklerini serileştirebilirsiniz. Ancak bunların serileştirme işlemini geri almak için statik bir fromJSON yöntemi yerine bağımsız documentSnapshotFromJSON ve querySnapshotFromJSON işlevlerini kullanmanız gerekir.

Örneğin, bir query işleminin querySnapshot sonuçları, toJSON yöntemi kullanılarak serileştirilebilir:

import {
  collection,
  getDocs,
  query,
  querySnapshotFromJSON
} from 'firebase/firestore';
// Assuming a configured instance of Firestore in the variable `firestore`.
const queryRef = query(collection(firestore, QUERY_PATH));
const querySnapshot = await getDocs(queryRef);
const querySnapshotJson = querySnapshot.toJSON();

Ardından, bu verilerin serileştirilmesi kaldırılabilir:

import {
  querySnapshotFromJSON
} from 'firebase/firestore';

// deserializedSnapshot is an object of type QuerySnapshot:

const deserializedSnapshot =
  querySnapshotFromJSON(firestore, querySnapshotJson);

Serileştirilmiş anlık görüntülere sahip dinleyiciler

SSR aşamasında sorgulanan veriler ilk CSR oluşturma işleminiz için değerli olsa da bu bilgilerin gerçek zamanlı güncellemeleri için Firestore hizmetini izlemeniz gerekebilir.

Uygulamanız bu gerçek zamanlı güncellemeleri gerektiriyorsa Firestore SnapshotListener'leri serileştirilmiş Snapshot verileriyle başlatmak için onSnapshotResume işlevini kullanabilirsiniz. Örneğin:

const observer = {
  next: (qs) => {
    console.log("onSnapshot invoked: ", qs.data());
  },
  error: (e) => {
    console.log("error callback invoked: ", e.toString());
  }
};
const unsubscribe = onSnapshotResume(firestore, querySnapshotJson, observer);