@nardole/firebase-core

A tiny, framework-agnostic wrapper to initialize a single Firebase App once and reuse it everywhere — React, Node, plain JS, or Micro‑Frontends.

• Why
• Features
• Installation
• Quick Start
• Usage (Vanilla)
• Micro‑Frontend (MFE)
• TypeScript
• API
• Compatibility
• FAQ
• License

Why

Firebase initialization is often duplicated across apps and MFEs. This package centralizes it behind a shared singleton to avoid multiple initializations in the same page/process.

Features

• Single entry point to initialize Firebase with FirebaseOptions and optional app name
• Stable, typed access to the current FirebaseApp instance
• Explicit errors if used before initialization
• Works with or without React — ideal for MFE architectures

Installation

• pnpm add @nardole/firebase-core firebase
• npm install @nardole/firebase-core firebase
• yarn add @nardole/firebase-core firebase

Quick Start

1. Grab your Firebase config from the Console.
2. Initialize once during app bootstrap.
3. Consume the shared instance from any module.

Usage (Vanilla)

import { firebaseService } from '@nardole/firebase-core';

firebaseService.init({
  apiKey: 'YOUR_API_KEY',
  authDomain: 'YOUR_AUTH_DOMAIN',
  projectId: 'YOUR_PROJECT_ID',
  appId: 'YOUR_APP_ID',
});

// Later in any module/file (even outside React)
const app = firebaseService.app;

Micro‑Frontend (MFE)

Initialize in the shell (or any federated module) and reuse in other MFEs. Prevents duplicate initialization and keeps state consistent.

// shell
import { firebaseService } from '@nardole/firebase-core';
firebaseService.init({ /* options */ });

// any mfe
import { firebaseService } from '@nardole/firebase-core';
const app = firebaseService.app;

TypeScript

• First‑class support. Import types from firebase/app as usual.

API

| Item | Signature | Parameters | Returns | Errors/Notes | | --- | --- | --- | --- | --- | | initialize | firebaseService.init(options: FirebaseOptions, name?: string, override?: boolean): void | - options: FirebaseOptions (required) - name: string (optional) - override: boolean (optional) | void | Initializes the app. If an app already exists and override is not true, throws "Firebase app already initialized". | | current app | firebaseService.app | — | FirebaseApp | Getter. If not initialized, throws "Firebase app not initialized". | | analytics | firebaseService.analytics | — | Analytics | Lazy getter; creates Analytics tied to the current app on first access. | | performance | firebaseService.performance | — | FirebasePerformance | Lazy getter; creates Performance tied to the current app on first access. | | remote config | firebaseService.remoteConfig | — | RemoteConfig | Lazy getter; creates Remote Config for the current app on first access. | | storage | firebaseService.storage | — | FirebaseStorage | Lazy getter; creates Storage for the current app on first access. | | auth | firebaseService.auth | — | Auth | Lazy getter; creates Auth for the current app on first access. | | database | firebaseService.database | — | Database | Lazy getter; creates Realtime Database for the current app on first access. | | firestore | firebaseService.firestore | — | Firestore | Lazy getter; creates Firestore for the current app on first access. |

Compatibility

• Peer: firebase ^12
• Runtime: Node 16+ or modern browsers

FAQ

• Q: Can I call init more than once?
  • A: Repeated calls without override will throw for safety. In controlled scenarios (e.g., the React Provider), the package may call init(..., ..., true) to overwrite.
• Q: Can I use it without React?
  • A: Yes. The package is framework‑agnostic.

License

MIT