@api-buddy/firebase-utils

Shared Firebase utilities for API Buddy plugins, providing consistent Firebase initialization, emulator support, and error handling.

Features

• 🔥 Firebase Admin & Client Initialization - Simple and consistent initialization of Firebase Admin and Client SDKs
• 🧪 Emulator Support - Built-in support for Firebase emulators with automatic configuration
• 🛡️ Type Safety - Full TypeScript support with comprehensive type definitions
• 🚦 Error Handling - Consistent error handling with custom error types and utilities
• 🔍 Validation - Runtime validation for Firebase configurations
• 🔌 Modular - Import only what you need to keep your bundle size small

Installation

# Using pnpm (recommended)
pnpm add @api-buddy/firebase-utils firebase firebase-admin

# Using npm
npm install @api-buddy/firebase-utils firebase firebase-admin

# Using yarn
yarn add @api-buddy/firebase-utils firebase firebase-admin

Usage

Basic Initialization

import {
  initializeFirebaseAdmin,
  initializeFirebaseClient,
  validateFirebaseConfig,
} from '@api-buddy/firebase-utils';

// Define your Firebase configuration
const config = {
  projectId: 'your-project-id',
  useEmulators: process.env.NODE_ENV === 'development',
  emulatorHosts: {
    auth: 'localhost:9099',
    firestore: 'localhost:8080',
    // ... other emulator hosts
  },
  clientConfig: {
    apiKey: 'your-api-key',
    authDomain: 'your-project-id.firebaseapp.com',
    projectId: 'your-project-id',
    // ... other Firebase config
  },
};

// Validate configuration
const validatedConfig = validateFirebaseConfig(config);

// Initialize Firebase Admin
const { adminApp, adminAuth, firestore } = await initializeFirebaseAdmin(validatedConfig);

// Initialize Firebase Client (browser)
const { app, auth, firestore: clientFirestore } = await initializeFirebaseClient(validatedConfig);

Error Handling

import { ERROR_CODES, isFirebaseUtilsError } from '@api-buddy/firebase-utils';

try {
  // Your Firebase operations
} catch (error) {
  if (isFirebaseUtilsError(error)) {
    console.error(`Firebase error (${error.code}):`, error.message);
    
    if (error.code === ERROR_CODES.ADMIN_INIT_FAILED) {
      // Handle specific error
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

Emulator Configuration

import { getDefaultEmulatorHosts } from '@api-buddy/firebase-utils';

// Get default emulator hosts
const emulatorHosts = getDefaultEmulatorHosts();
// {
//   auth: 'localhost:9099',
//   firestore: 'localhost:8080',
//   database: 'localhost:9000',
//   storage: 'localhost:9199',
//   functions: 'localhost:5001'
// }

// Use with your config
const config = {
  projectId: 'your-project-id',
  useEmulators: true,
  emulatorHosts: {
    ...emulatorHosts,
    // Override specific hosts if needed
    auth: 'localhost:9999',
  },
};

API Reference

Functions

initializeFirebaseAdmin(config: FirebaseUtilsConfig): Promise<FirebaseAdminInstances>

Initializes the Firebase Admin SDK with the provided configuration.

initializeFirebaseClient(config: FirebaseUtilsConfig): Promise<FirebaseClientInstances>

Initializes the Firebase Client SDK with the provided configuration.

validateFirebaseConfig(config: unknown): FirebaseUtilsConfig

Validates the Firebase configuration object against the expected schema.

getDefaultEmulatorHosts(): Record<string, string>

Returns the default emulator host configuration.

Error Handling

FirebaseUtilsError

Custom error class for Firebase-related errors.

ERROR_CODES

Enum of possible error codes.

isFirebaseUtilsError(error: unknown): error is FirebaseUtilsError

Type guard to check if an error is a FirebaseUtilsError.

License

MIT