Firebase Admin SDK v14移行入門——Next.js + FirestoreをNode.js 22へ上げる

はじめに

Next.js App RouterでFirestoreを使っていて、こんな状態になっていませんか？

• GitHub Actionsや本番環境のNode.jsが20のまま固定されている
• firebase-admin の古いnamespace形式がServer ActionやRoute Handlerに残っている
• Firestore、Authentication、Cloud Messagingの管理者処理が1つの巨大な初期化ファイルに集まっている
• SDKのメジャーアップデートを「ビルドが通るか」だけで判断している

2026年6月8日、Firebase Admin Node.js SDK 14.0.0が公開されました。公式リリースノートでは、Node.js 18と20のサポート終了、legacy namespace supportの削除、deprecated Instance ID APIの削除、SDK全体のエラー処理刷新などが案内されています。特にNext.js + Firestoreのサーバー処理でAdmin SDKを使っているチームは、Node.js 22以上へ上げる計画が必要です。

本記事では、架空の予約管理SaaS「YoyakuLane」を題材に、Firebase Admin SDK v14へ移行する実践手順を整理します。読み終えると、Node.js 22への引き上げ、ES module entry pointへの書き換え、GitHub Actionsでの検証入口までを具体化できます。

参考にした一次情報は次の通りです。

• Firebase Admin Node.js SDK Release Notes
• Add the Firebase Admin SDK to your server
• firebase-admin-node releases
• Node.js 22 is now available

何が変わったのか

v14は「いつもの依存更新」ではなく、実行環境とimport方針を同時に見直すメジャーアップデートです。まず影響範囲を表で整理します。

移行の全体像は次のようになります。

ポイントは、SDKだけを上げて終わりにしないことです。Admin SDKは管理者権限でFirestoreやAuthenticationへアクセスするため、「どのランタイムで、どのサーバー処理が、どの権限で動くか」を先に見ます。

事前準備: 影響範囲を洗い出す

YoyakuLaneは、店舗予約、スタッフ権限、通知履歴をFirestoreに保存するNext.jsアプリという想定です。まず、Admin SDKを使う箇所を探します。

rg "firebase-admin|admin\\." src app lib
node --version
yarn why firebase-admin

yarn why firebase-admin では、直接依存か、別パッケージ経由かを確認できます。まだ導入していない場合、Firebase公式ドキュメントにあるnpmパッケージ名は firebase-admin です。Yarnプロジェクトでは次のように追加します。

yarn add firebase-admin@^14

次に、更新対象を4つに分けます。

ハンズオン1: Node.js 22へそろえる

最初に、ローカルとCIのNode.jsをそろえます。.node-version を使っている場合は22系へ上げます。

22

必要であれば package.json の engines.node も >=22 にして、レビュー時に意図が見えるようにします。

GitHub Actionsでは、PRごとにNode.js 22でビルドします。

name: Web CI

on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "yarn"

      - run: yarn install --frozen-lockfile
      - run: yarn build

この段階では、まだ業務コードを書き換えません。まず「Node.js 22で依存関係が解決できるか」「既存のNext.jsビルドが落ちないか」を見ます。

ハンズオン2: Admin SDKのimportを分割する

Firebase公式ドキュメントでは、Admin SDKの初期化例として firebase-admin/app から initializeApp をimportする形が案内されています。v14ではlegacy namespace supportが削除されたため、古いnamespaceに寄った書き方を残さないようにします。

避けたい形は次のようなnamespace依存です。

import * as admin from "firebase-admin";

export const db = admin.firestore();
export const auth = admin.auth();

FirestoreとAuthenticationを使うだけなら、entry pointごとに分けます。

// src/lib/firebase/admin.ts
import { getApps, initializeApp } from "firebase-admin/app";
import { getAuth } from "firebase-admin/auth";
import { getFirestore } from "firebase-admin/firestore";

const app = getApps().length === 0 ? initializeApp() : getApps()[0];

export const adminDb = getFirestore(app);
export const adminAuth = getAuth(app);

Firebase App Hosting、Cloud Run、App Engine、Cloud Functions for FirebaseのようなGoogle環境では、公式ドキュメント上、Application Default Credentialsによる初期化が推奨されています。ローカルでサービスアカウント鍵を使う場合も、鍵JSONをリポジトリに置かず、環境変数やシークレット管理に寄せます。

ハンズオン3: Server ActionのFirestore処理を移行する

予約確定処理を例にします。YoyakuLaneでは、reservations と auditLogs を同じServer Actionから更新します。Admin SDKはクライアントへ渡さず、サーバー専用ファイルからだけ呼びます。

// src/app/reservations/[reservationId]/actions.ts
"use server";

import { FieldValue } from "firebase-admin/firestore";
import { adminDb } from "@/lib/firebase/admin";

type ConfirmReservationInput = {
  reservationId: string;
  operatorId: string;
};

export async function confirmReservation(input: ConfirmReservationInput) {
  if (!input.reservationId || !input.operatorId) {
    throw new Error("reservationId and operatorId are required");
  }

  const reservationRef = adminDb
    .collection("reservations")
    .doc(input.reservationId);
  const auditLogRef = adminDb.collection("auditLogs").doc();

  await adminDb.runTransaction(async (tx) => {
    const snapshot = await tx.get(reservationRef);
    if (!snapshot.exists) throw new Error("Reservation not found");

    tx.update(reservationRef, {
      status: "confirmed",
      confirmedAt: FieldValue.serverTimestamp(),
      confirmedBy: input.operatorId,
    });

    tx.create(auditLogRef, {
      action: "reservation.confirm",
      reservationId: input.reservationId,
      operatorId: input.operatorId,
      createdAt: FieldValue.serverTimestamp(),
    });
  });
}

Firestoreの書き込み自体は従来通りですが、移行時には「Admin SDKの初期化が1箇所に閉じているか」「ブラウザ側bundleへ firebase-admin が混ざらないか」を確認します。Next.jsでは、Server Actionファイルに "use server" を付け、UIコンポーネントからAdmin SDKを直接importしない構成にします。

大規模移行の進め方

20〜30個のAdmin SDK利用箇所がある場合、全部を1PRで直すとレビューが重くなります。3〜4タスクずつ分けるのが実務的です。

特にCloud Messagingを使っている場合は、公式リリースノートにあるlegacy message types削除の影響を受けやすいです。DataMessagePayload や MessagingPayload のような古い型名が残っていないか、検索で確認してから進めます。

まとめ

Firebase Admin SDK v14への移行で見るべき点は、単なるパッケージ更新ではありません。

• Node.js 18/20の前提をやめ、Node.js 22以上へそろえる
• firebase-admin/app、firebase-admin/firestore、firebase-admin/auth のようにentry point importへ寄せる
• Server ActionやRoute Handler内にAdmin権限を閉じ込め、クライアントbundleへ混ぜない
• Instance ID APIやCloud Messagingの古い型が残っていないか確認する
• GitHub ActionsでNode.js 22の yarn build を固定し、移行PRを小さく分ける

Next.js + Firestoreの業務アプリでは、Admin SDKは予約確定、監査ログ、権限変更、通知などの重要な処理を担います。v14移行は後回しにせず、まずNode.js 22のCIを1本作り、影響範囲を見える化するところから始めるのがおすすめです。