Firebase JavaScript SDK のベスト プラクティス

このページでは、Firebase JavaScript SDK の使用時に発生する可能性のある JavaScript の問題に関するヒントとトラブルシューティングについて説明します。

その他の課題がある場合や、該当する問題が見つからない場合は、メインの Firebase のよくある質問で、Firebase 全体またはプロダクト固有のよくある質問をご覧ください。

また、Firebase JavaScript SDK GitHub リポジトリで報告された問題とトラブルシューティングの最新リストをご確認いただき、このリポジトリに問題を報告することもできます。

Node.js コンストラクト用の Admin SDK は Firebase JavaScript SDK と互換性がありません

Node.js の Firebase Admin SDK と Firebase JavaScript SDK は、インターフェース、クラス、関数の定義を共有しない、異なる実装です。 Admin SDK オブジェクトのインスタンスは、Firebase JavaScript SDK 関数と互換性がありません。

たとえば、Admin SDK の FirebaseApp のインスタンスが Firebase JavaScript SDK getDatabase 関数に渡されると、次のエラーが発生します。

TypeError: Cannot read properties of undefined (reading 'getProvider')
 at _getProvider
 at getDatabase

これは、Realtime Database だけでなく、Firebase JavaScript SDK API サーフェス全体に当てはまります。 逆方向での使用についても同様です。Cloud Firestore JS SDK の Timestamp 型を Node.js 用 Firebase Admin SDK で使用しようとすると、同様のエラーが発生します。

競合するバージョンの Firebase JavaScript SDK を使用しないようにする

1 つのプロジェクト内に Firebase JavaScript SDK の競合する複数のバージョンが依存関係として構成されていると、SDK インスタンスが SDK パッケージ間で渡されるときにランタイム エラーが発生します。たとえば、FirebaseApp のバージョンが一致しない Data Connect ライブラリを使用すると、次のエラーが発生します。

Error: Component data-connect has not been registered yet

この問題は、Firebase SDK パッケージの一部ではなく 1 つの依存関係が更新された場合に一般的に発生します。この状況は、依存関係の自動更新ツールにより、プロジェクトの yarn.lock ファイルまたは package-lock.json ファイル内の Firebase SDK 依存関係のサブセットが変更された場合に発生することがよくあります。多くの Firebase JavaScript SDK は相互運用されるため、さまざまなバージョンの SDK を使用すると、ランタイムの互換性が失われます。

この問題を解決するには、プロジェクトの node_modules/ ディレクトリと yarn.lock（yarn の場合）または package-lock.json（npm の場合）を削除し、依存関係を再インストールします。

それでもエラーが解決しない場合は、npm ls コマンドを使用して問題をさらにデバッグします。このコマンドは、プロジェクトの依存関係をログに記録して、競合するバージョンの firebase モジュールを特定できるようにします。

たとえば、次のログは、package-using-older-firebase が競合するバージョンの Firebase JavaScript SDK をインポートしていることを示しています。

$ npm ls firebase --all
your-app@0.0.0
├── firebase@11.2.0
├─┬ @angular/fire@19.0.0
│ ├── firebase@11.2.0 deduped
│ └─┬ rxfire@6.1.0
│   └── firebase@10.14.1 deduped
└─┬ package-using-older-firebase@0.1.0
  └─── firebase@10.14.1

アプリで CJS と ESM の require ステートメントと import ステートメントを混在させると、エラーが発生することもあります。これにより、Firebase JavaScript SDK の複数のインスタンスが作成され、それぞれが異なるため、Firebase JavaScript SDK の相互運用性が損なわれます。このシナリオをデバッグするには、使用するバンドラーの詳細度を増やします。たとえば、この目的のために esbuild analyze フラグを使用できます。

サービス ワーカーがバンドルされていることを確認する

サービス ワーカーは、多くの場合、他のウェブアプリとは別のパイプラインからビルドされ、Webpack などのバンドラーのデフォルト構成には含まれません。

サービス ワーカー内で Firebase JavaScript SDK のモジュラー バージョンを使用する場合は、サービス ワーカーのソースファイルを含めるようにアプリ バンドラーを構成してください。次の例では、npx を使用して、プロジェクトの src ディレクトリに firebase-sw.js Service Worker をバンドルします。

npx esbuild ./src/firebase-sw.js --bundle --minify --main-fields=webworker,browser,module,main,default --outfile=public/firebase-sw.js

バンドルされていないサービス ワーカーの有効化は、サービス ワーカーをサポートしていない ES モジュールのインポート元や、サービス ワーカーのスコープに存在しないファイルをソースとしている場合、失敗します。このような障害はサイレントで、デバッグが難しい場合があります。

モジュラー バージョンの Firebase JavaScript SDK をアプリにバンドルする際の詳細については、Firebase でのモジュール バンドラの使用をご覧ください。

または、CDN から compat Firebase JavaScript SDK バンドルをインポートして、バンドルを不要にすることもできます。

// Give the service worker access to Firebase Messaging.
// Replace 10.13.2 with the version of the Firebase JS SDK you're using
// in your app.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.js');

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
  ...
});

// Retrieve an instance of Firebase Messaging so that it can handle
// background messages.
const messaging = firebase.messaging();

サーバーサイド レンダリングを操作するときに FirebaseServerApp を使用する

Firebase JavaScript SDK は元々、ブラウザ環境での実行を目的としていました。サーバーサイド レンダリング（SSR）フレームワークの導入により、SDK の使用が新しいランタイム環境に移行しています。これらのランタイムには、ウェブブラウザで提供されるツールと API のサブセットが用意されています。

たとえば、一部の Firebase SDK では、IndexedDB（ブラウザ専用の API）によるデータ キャッシュが必要です。Firebase Auth では、特定のログインフローでユーザー操作が必要になる場合がありますが、ヘッドレス サーバー環境ではこれは不可能です。App Check は、App Check トークンを作成する前に、ブラウザのヒューリスティックを使用してユーザーを検証します。

このような新しい環境で SDK を使用する場合は、FirebaseServerApp を使用します。これは FirebaseApp の新しいバリアントであり、クライアントサイドから収集されたデータを使用して SSR Firebase インスタンスをプリロードする手段を提供します。

FirebaseServerApp は次の 2 つのパラメータをサポートしています。

  • 認証 ID トークン: 指定した場合、Firebase Auth は以前に認証されたユーザーを自動的にログインさせます。CSR と SSR の境界を越えてセッションをまたぐ可能性があります。
  • App Check トークン: 指定した場合、App Check クライアント（ブラウザ環境以外ではサポートされていません）のインスタンスを初期化することなく、他の Firebase SDK でトークンが使用されます。これにより、App Check が有効になっているプロダクト（Cloud Functions、Data Connect、Cloud Firestore、Realtime Database、Vertex AI など）に対する SSR サポートのブロックが解除されます。

Next.js での FirebaseServerApp の使用例については、FirebaseServerApp を使用して SSR アプリ開発を効率化するをご覧ください。