Required dependencies

npm install @fastify/busboy @firebase/database-compat @firebase/database-types \
  farmhash-modern fast-deep-equal google-auth-library jsonwebtoken jwks-rsa \
  node-forge uuid

No native build steps, iOS pod install, or Android linking are required. This is a pure Node.js package. Node.js 20 or higher is strongly recommended (18 is deprecated).

Project setup

1. Drop the source into your project, e.g. src/vendor/firebase-admin/. The internal imports use relative paths and will resolve correctly from that location.

2. TypeScript config — ensure src/vendor/firebase-admin/ is inside your rootDir and that esModuleInterop is enabled:

{
  "compilerOptions": {
    "rootDir": "src",
    "esModuleInterop": true,
    "module": "commonjs",
    "target": "ES2020",
    "strict": true,
    "resolveJsonModule": true
  }
}

3. Path alias (optional) — add a path alias so your app imports cleanly:

{
  "compilerOptions": {
    "paths": {
      "firebase-admin/*": ["./src/vendor/firebase-admin/*"]
    }
  }
}

4. Service account credentials — set one of the following environment variables before the process starts:

# Option A: path to a service account JSON file
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccount.json"

# Option B: inline JSON (useful in containerized environments)
export FIREBASE_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'

5. Initialize once at application startup, before any Firebase service is accessed:

import { initializeApp, cert } from './vendor/firebase-admin/app';

initializeApp({
  credential: cert('/path/to/serviceAccount.json'),
  databaseURL: 'https://<PROJECT_ID>.firebaseio.com',
});

Public API

initializeApp

import { initializeApp, AppOptions } from './vendor/firebase-admin/app';

function initializeApp(options?: AppOptions, name?: string): App;

Creates and registers a Firebase App instance. Call once at server startup. Pass options with a credential and optional databaseURL, storageBucket, projectId. A second name argument supports multiple app instances.

getAuth

import { getAuth } from './vendor/firebase-admin/auth';

function getAuth(app?: App): Auth;

Returns the Auth service for the default app or a given App. Use this to verify ID tokens, create custom tokens, manage users, and configure multi-tenancy. Call without arguments after initializeApp() to use the default app.

getAppCheck

import { getAppCheck } from './vendor/firebase-admin/app-check';

function getAppCheck(app?: App): AppCheck;

Returns the AppCheck service. Use it to verify App Check tokens sent from client applications, protecting backend endpoints from abuse. Accepts an optional App for multi-app setups.

applicationDefault / cert / refreshToken

import { applicationDefault, cert, refreshToken } from './vendor/firebase-admin/app';

function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAgent?: Agent): Credential;
function applicationDefault(httpAgent?: Agent): Credential;
function refreshToken(refreshTokenPathOrObject: string | object, httpAgent?: Agent): Credential;

Credential factories. Use cert with an explicit service account, applicationDefault on Google Cloud infrastructure (GCE, Cloud Run, GKE), or refreshToken for OAuth2 refresh-token files.

Working examples

Scenario - Verify a Firebase ID token in an Express middleware

A common backend pattern: protect an API route by verifying the Firebase ID token passed in the Authorization header.

import express, { Request, Response, NextFunction } from 'express';
import { initializeApp, cert } from './vendor/firebase-admin/app';
import { getAuth } from './vendor/firebase-admin/auth';

initializeApp({ credential: cert(process.env.GOOGLE_APPLICATION_CREDENTIALS!) });

const app = express();

async function firebaseAuth(req: Request, res: Response, next: NextFunction) {
  const header = req.headers.authorization ?? '';
  if (!header.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing token' });
  }
  const idToken = header.slice(7);
  try {
    const decoded = await getAuth().verifyIdToken(idToken);
    (req as any).uid = decoded.uid;
    next();
  } catch {
    res.status(403).json({ error: 'Invalid token' });
  }
}

app.get('/profile', firebaseAuth, (req, res) => {
  res.json({ uid: (req as any).uid });
});

app.listen(3000);

Scenario - Create a custom token for a server-side sign-in

Mint a custom Firebase token so a server process or a trusted third-party service can authenticate as a specific user.

import { initializeApp, cert } from './vendor/firebase-admin/app';
import { getAuth } from './vendor/firebase-admin/auth';

initializeApp({ credential: cert('./serviceAccount.json') });

async function mintToken(uid: string, claims: Record<string, unknown>): Promise<string> {
  const customToken = await getAuth().createCustomToken(uid, claims);
  return customToken;
}

mintToken('user-123', { role: 'admin', plan: 'pro' }).then((token) => {
  console.log('Custom token:', token);
});

Scenario - Verify an App Check token before processing a sensitive request

Protect a sensitive endpoint by confirming the request originates from a legitimate app instance.

import { initializeApp, applicationDefault } from './vendor/firebase-admin/app';
import { getAppCheck, VerifyAppCheckTokenResponse } from './vendor/firebase-admin/app-check';

initializeApp({ credential: applicationDefault() });

async function verifyRequest(appCheckToken: string): Promise<VerifyAppCheckTokenResponse> {
  const result = await getAppCheck().verifyToken(appCheckToken);
  return result;
}

// In your request handler:
async function handler(req: any, res: any) {
  const token = req.headers['x-firebase-appcheck'] as string;
  try {
    const { appId } = await verifyRequest(token);
    console.log('Verified app:', appId);
    res.json({ ok: true });
  } catch {
    res.status(401).json({ error: 'App Check failed' });
  }
}

File walkthrough

• index.ts - Entry point that re-exports the default Firebase namespace and emits a warning if loaded in a browser.
• default-namespace.ts / default-namespace.d.ts - The legacy admin.* surface (e.g. admin.auth(), admin.firestore()). Kept for backward compat.
• firebase-namespace-api.ts - TypeScript interfaces describing the full namespace shape, used for typing the default export.
• index.d.ts - Ambient declarations for the top-level module.
• app/ - initializeApp, getApp, getApps, deleteApp, App, AppOptions, credential types, and SDK version constant.
• app-check/ - AppCheck class, token generation, token verification, and associated API types.
• auth/ - Full Auth implementation: Auth, BaseAuth, user record types, token generator/verifier, tenant manager, project config manager.
• credential/ - Re-exports credential factories and types under the credential namespace for legacy compatibility.
• data-connect/ - Data Connect service class and internal API client.
• database/ - Realtime Database service wrapper and namespace.
• eventarc/ - Eventarc channel client for publishing CloudEvents.
• extensions/ - Firebase Extensions runtime config API.
• firestore/ - Firestore service wrapper; delegates to @google-cloud/firestore.
• functions/ - Cloud Functions task queue enqueue client.
• installations/ - Firebase Installations service.
• instance-id/ - Legacy Instance ID API.
• machine-learning/ - Firebase ML custom model management.
• messaging/ - FCM send, subscribe, unsubscribe, and batch send.
• phone-number-verification/ - Phone number verification helpers.
• project-management/ - Firebase project and app metadata management.
• remote-config/ - Remote Config template fetch, publish, and rollback.
• security-rules/ - Firestore and Storage security rules management.
• storage/ - Cloud Storage getStorage() and bucket helpers.
• utils/ - Shared error classes (FirebaseAppError, AppErrorCodes), HTTP utility functions, and getSdkVersion().

Common pitfalls and fixes

• initializeApp called multiple times — calling it more than once without a name argument throws "Firebase App named '[DEFAULT]' already exists". Guard with getApps().length === 0 before calling initializeApp.
• GOOGLE_APPLICATION_CREDENTIALS not set and using applicationDefault() — the SDK throws a credential error at runtime. Set the env var to the absolute path of a service account JSON file, or use cert() with an explicit path.
• ESM/CJS interop — index.ts uses export = (CommonJS-style). In an ESM project, import with import admin = require('./vendor/firebase-admin') or enable esModuleInterop: true and use import * as admin from './vendor/firebase-admin'.
• Node.js version — the SDK officially requires Node.js 18+; Node.js 20+ is strongly recommended. Running on Node.js 16 or below will cause runtime failures in dependencies like google-auth-library.
• Multiple Firebase apps — when using getAuth() / getAppCheck() without an argument, they bind to the default app. In multi-tenant scenarios, pass the specific App instance returned by initializeApp(options, 'appName').
• farmhash-modern is a native addon — it compiles via node-gyp. Ensure python3, make, and a C++ compiler are available in your build environment, especially inside Docker images.

Vibe-coding prompt template

I have vendored the Firebase Admin Node.js SDK source (firebase-admin@13.8.0)
into my project at `src/vendor/firebase-admin/`. There is a USAGE.md at the
root of that directory explaining the layout, exports, and working examples.

Please help me integrate this SDK into my existing Node.js / TypeScript / Express project:

1. Read USAGE.md and the source structure under `src/vendor/firebase-admin/`.
2. Add `initializeApp` initialization at server startup using the `cert` credential
   factory, pulling the service account path from the `GOOGLE_APPLICATION_CREDENTIALS`
   environment variable.
3. Add an Express middleware that verifies Firebase ID tokens using `getAuth().verifyIdToken()`.
4. Wire the middleware onto the protected routes in my existing router.
5. Ensure `tsconfig.json` has `esModuleInterop: true` and that the vendor path
   is inside `rootDir`.
6. Do not install the npm package `firebase-admin`; all imports must point to
   `src/vendor/firebase-admin/` using relative paths or the path alias defined
   in tsconfig.
7. Show me the final file changes step by step.

License and credit

The Firebase Admin Node.js SDK is licensed under the Apache License, Version 2.0. See source/LICENSE if present, or refer to the official repository.

Upstream npm package: firebase-admin — maintained by Google LLC / the Firebase team.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.