No native build steps, pod installs, or Android linking are required. This package is server-side only; do not use in browsers or React Native clients.

Project setup

1. Copy the source/ directory into your project, e.g. src/firebase-admin/.

2. In tsconfig.json, ensure paths and moduleResolution are set:

{
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "node",
    "target": "ES2020",
    "strict": true,
    "esModuleInterop": true,
    "paths": {
      "firebase-admin/app": ["./src/firebase-admin/app/index.ts"],
      "firebase-admin/auth": ["./src/firebase-admin/auth/index.ts"],
      "firebase-admin/messaging": ["./src/firebase-admin/messaging/index.ts"],
      "firebase-admin/app-check": ["./src/firebase-admin/app-check/index.ts"]
    }
  }
}

3. Set environment variables before running your server:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json"
# OR set FIREBASE_CONFIG for Firebase-hosted environments

4. Initialize the app once at process startup (see examples below). All sub-packages call getApp() internally; initialization must happen first.

5. For service account file auth without GOOGLE_APPLICATION_CREDENTIALS:

import { initializeApp, cert } from './src/firebase-admin/app/index';
initializeApp({ credential: cert('./serviceAccountKey.json') });

Public API

initializeApp

import { initializeApp, AppOptions } from 'firebase-admin/app';
function initializeApp(options?: AppOptions, name?: string): App;

Initializes a Firebase app instance. Call once at server startup with credentials and optional config. Pass name when managing multiple Firebase projects simultaneously.

getAuth

import { getAuth } from 'firebase-admin/auth';
function getAuth(app?: App): Auth;

Returns the Auth service for the default app or a named app. Use it for verifying ID tokens, creating custom tokens, managing users, and setting custom claims.

getAppCheck

import { getAppCheck } from 'firebase-admin/app-check';
function getAppCheck(app?: App): AppCheck;

Returns the AppCheck service. Use it to verify App Check tokens from client requests, ensuring only legitimate app instances access your backend.

cert

import { cert } from 'firebase-admin/app';
function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAgent?: Agent): Credential;

Creates a Credential from a service account JSON file path or object. Pass this to initializeApp({ credential: cert(...) }) when not using Application Default Credentials.

applicationDefault

import { applicationDefault } from 'firebase-admin/app';
function applicationDefault(httpAgent?: Agent): Credential;

Returns a credential sourced from GOOGLE_APPLICATION_CREDENTIALS or the GCP metadata server. Preferred for Cloud Run, GKE, and App Engine deployments.

Working examples

Scenario - Initialize and verify an ID token

A typical Express middleware that validates a Firebase Auth ID token on every request.

import { initializeApp, applicationDefault } from './src/firebase-admin/app/index';
import { getAuth } from './src/firebase-admin/auth/index';
import type { Request, Response, NextFunction } from 'express';

initializeApp({ credential: applicationDefault() });

async function firebaseAuthMiddleware(
  req: Request,
  res: Response,
  next: NextFunction
): Promise<void> {
  const authHeader = req.headers.authorization ?? '';
  if (!authHeader.startsWith('Bearer ')) {
    res.status(401).json({ error: 'Missing Bearer token' });
    return;
  }
  const idToken = authHeader.split('Bearer ')[1];
  try {
    const decodedToken = await getAuth().verifyIdToken(idToken);
    (req as any).uid = decodedToken.uid;
    next();
  } catch (err) {
    res.status(403).json({ error: 'Invalid or expired token' });
  }
}

export { firebaseAuthMiddleware };

Scenario - Create a custom auth token for a service account user

Generate a custom token to sign in a user from the server, e.g. after validating a third-party identity.

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

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

async function mintCustomToken(uid: string, role: string): Promise<string> {
  const auth = getAuth();
  const customToken = await auth.createCustomToken(uid, { role });
  return customToken;
}

// Usage
mintCustomToken('user-123', 'admin').then((token) => {
  console.log('Custom token:', token);
});

Scenario - Verify an App Check token in a Cloud Function or Express handler

Protect a backend endpoint so only attested client apps can call it.

import { initializeApp, applicationDefault } from './src/firebase-admin/app/index';
import { getAppCheck, VerifyAppCheckTokenResponse } from './src/firebase-admin/app-check/index';
import type { Request, Response } from 'express';

initializeApp({ credential: applicationDefault() });

async function verifiedEndpoint(req: Request, res: Response): Promise<void> {
  const appCheckToken = req.header('X-Firebase-AppCheck');
  if (!appCheckToken) {
    res.status(401).json({ error: 'App Check token missing' });
    return;
  }
  try {
    const result: VerifyAppCheckTokenResponse = await getAppCheck().verifyToken(appCheckToken);
    if (result.alreadyConsumed) {
      res.status(401).json({ error: 'Token already consumed (replay attack)' });
      return;
    }
    res.json({ message: 'Access granted', appId: result.appId });
  } catch {
    res.status(401).json({ error: 'Invalid App Check token' });
  }
}

export { verifiedEndpoint };

File walkthrough

• index.ts - Legacy CommonJS entry point; exports the entire firebase default namespace via export =. Use sub-package imports instead for new code.
• default-namespace.ts / default-namespace.d.ts - Assembles the legacy admin.* namespace shape for backward compatibility with v8-style imports.
• firebase-namespace-api.ts - TypeScript interfaces defining the full legacy namespace API surface.
• app/ - initializeApp, getApp, getApps, deleteApp, App, AppOptions, credential types, and the FirebaseApp class that all services attach to.
• app-check/ - AppCheck service class, token verification, and the getAppCheck() factory.
• auth/ - Auth and BaseAuth classes covering all user and token management operations.
• credential/ - Re-exports credential factory functions and the legacy admin.credential namespace wrapper.
• data-connect/ - Admin client for Firebase Data Connect mutations and queries.
• database/ - Admin wrapper around the Firebase Realtime Database SDK.
• eventarc/ - Client for publishing CloudEvents to Eventarc channels.
• extensions/ - Admin API for managing Firebase Extensions runtime configuration.
• firestore/ - Thin integration layer exposing the @google-cloud/firestore client via Firebase app context.
• functions/ - Cloud Tasks-backed Cloud Functions enqueue API and direct callable invocation.
• installations/ - Firebase Installations service admin access.
• instance-id/ - Legacy FCM Instance ID service (deprecated; prefer messaging).
• machine-learning/ - Firebase ML custom model upload and management.
• messaging/ - FCM send API: send, sendEach, sendMulticast, topic management.
• phone-number-verification/ - Server-side phone number verification helpers.
• project-management/ - Manage Firebase project apps (iOS/Android/Web).
• remote-config/ - Fetch, modify, and publish Remote Config templates.
• security-rules/ - Programmatic management of Firestore and Storage security rules.
• storage/ - Admin access to Cloud Storage buckets via the Firebase app.
• utils/ - Shared utilities: HTTP client, error classes (FirebaseAppError, AppErrorCodes), SDK version.

Common pitfalls and fixes

• Multiple initializeApp calls crash the process: Call initializeApp only once; wrap it in a guard with getApps().length === 0 or use a module-level singleton.
• GOOGLE_APPLICATION_CREDENTIALS not set in production: On non-GCP hosts, explicitly pass cert(serviceAccount) to initializeApp; applicationDefault() silently fails without the env var.
• export = interop with ESM: index.ts uses export =; import with import firebase = require('firebase-admin') or set "esModuleInterop": true and use import * as firebase from 'firebase-admin'. Prefer sub-package imports to avoid this entirely.
• TypeScript path aliases not resolved at runtime: tsconfig.json paths are compile-time only; add tsconfig-paths or compile to JS with tsc and use the compiled output paths.
• Node.js version below 18: The SDK requires Node.js 18+; running on Node 16 causes subtle crypto and fetch failures. Pin your engine in package.json: "engines": { "node": ">=18" }.
• firebase-admin already installed alongside this source: If both the npm package and this source exist in the project, duplicate service registrations will throw. Use path aliases exclusively to redirect all imports to this source, or remove the npm package.

Vibe-coding prompt template

I have the Firebase Admin Node.js SDK TypeScript source in `src/firebase-admin/`
and a usage guide at `USAGE.md`. The upstream package is `user@example.com`.

Please help me integrate this into my existing Node.js/TypeScript project by doing
the following step by step:

1. Read `USAGE.md` in full for context on available exports and setup instructions.
2. Update `tsconfig.json` to add path aliases mapping `firebase-admin/app`,
   `firebase-admin/auth`, `firebase-admin/messaging`, and `firebase-admin/app-check`
   to the corresponding files under `src/firebase-admin/`.
3. Create `src/lib/firebase.ts` that initializes the Firebase app using
   `applicationDefault()` or a service account cert, and exports typed service
   accessors (`getAuth`, `getAppCheck`, etc.).
4. Add an Express middleware in `src/middleware/firebaseAuth.ts` that verifies
   Firebase ID tokens using `getAuth().verifyIdToken()` from the source, following
   the pattern in `USAGE.md`.
5. Show me how to call `getAuth().setCustomUserClaims()` to assign a role to a user.
6. Confirm all imports reference `src/firebase-admin/` (not the npm package) and
   that `initializeApp` is called exactly once.

Only use symbols and APIs documented in `USAGE.md` and visible in the source files.
Do not invent APIs.

License and credit

The Firebase Admin Node.js SDK is licensed under the Apache License, Version 2.0. Your use of Firebase services is additionally governed by the Firebase Terms of Service.

Upstream package: firebase-admin on npm - maintained by Google / the Firebase team. Source repository: firebase/firebase-admin-node.

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

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