@reggietheroman/nest-firebase

Reusable NestJS module that integrates with Firebase Admin SDK.
Supports Auth, Firestore, and Storage out of the box.

Installation

pnpm add @reggietheroman/nest-firebase firebase-admin

Peer dependencies (must already be installed in your NestJS project): • @nestjs/common • @nestjs/core • rxjs • firebase-admin

Setup

In your AppModule:

import { Module } from '@nestjs/common';
import {
  FirebaseCoreModule,
  FirebaseAuthModule,
  FirebaseFirestoreModule,
  FirebaseStorageModule,
} from '@reggietheroman/nest-firebase';

@Module({
  imports: [
    FirebaseCoreModule.register({
      projectId: process.env.FB_PROJECT_ID!,
      clientEmail: process.env.FB_CLIENT_EMAIL!,
      privateKey: process.env.FB_PRIVATE_KEY!, // supports escaped \n
      storageBucket: process.env.FB_STORAGE_BUCKET,
      databaseURL: process.env.FB_DATABASE_URL,
      // Optional emulators
      // emulators: { auth: 'localhost:9099', firestore: 'localhost:8080', storage: 'localhost:9199' },
    }),
    FirebaseAuthModule,
    FirebaseFirestoreModule,
    FirebaseStorageModule,
  ],
})
export class AppModule {}

Usage

Protect routes with Firebase ID tokens

import { Controller, Get, UseGuards } from '@nestjs/common';
import {
  FirebaseAuthGuard,
  FirebaseUser,
  FIREBASE_FIRESTORE,
  FIREBASE_BUCKET,
} from '@reggietheroman/nest-firebase';
import { Inject } from '@nestjs/common';
import type { firestore, storage } from 'firebase-admin';

@Controller()
export class ExampleController {
  constructor(
    @Inject(FIREBASE_FIRESTORE) private readonly db: firestore.Firestore,
    @Inject(FIREBASE_BUCKET) private readonly bucket?: storage.Bucket,
  ) {}

  @UseGuards(FirebaseAuthGuard)
  @Get('/members')
  async listMembers(@FirebaseUser() user: any) {
    const snap = await this.db.collection('members').limit(50).get();
    return {
      uid: user.uid,
      members: snap.docs.map((d) => ({ id: d.id, ...d.data() })),
    };
  }
}

Upload to Firebase Storage

import { Inject, Injectable } from '@nestjs/common';
import { FIREBASE_BUCKET } from '@reggietheroman/nest-firebase';
import type { storage } from 'firebase-admin';

@Injectable()
export class UploadService {
  constructor(@Inject(FIREBASE_BUCKET) private readonly bucket: storage.Bucket) {}

  async uploadBuffer(path: string, buf: Buffer, contentType?: string) {
    const file = this.bucket.file(path);
    await file.save(buf, { contentType, resumable: false, public: false });
    const [signedUrl] = await file.getSignedUrl({
      action: 'read',
      expires: Date.now() + 3600_000,
    });
    return { path, signedUrl };
  }
}

Features

• Dynamic module (register / registerAsync)
• Firebase Auth guard (FirebaseAuthGuard)
• Parameter decorators (@FirebaseUser, @FirebaseClaims)
• Injectable providers for Firestore, Storage, and Auth
• Emulator support for local testing
• Works with NestJS v10+

License

MIT

Unit Testing

Tests use Jest

run:

pnpm test

or in watch mode:

pnpm test:watch

__tests__ directory contain the test specs and test contains test utilities and setup code.

E2E Testing

TODO