ngx-firestore-wrapper-kit — Integration Guide

Steps to install, configure, and use this library in an Angular application.

1. Install

From npm

npm install ngx-firestore-wrapper-kit

2. Firebase configuration

Add the Firebase config to your environment file (src/environments/environment.ts):

import { FirebaseOptions } from '@angular/fire/app';

export const environment = {
  production: false,
  firebaseConfig: {
    apiKey: 'YOUR_API_KEY',
    authDomain: 'YOUR_PROJECT.firebaseapp.com',
    projectId: 'YOUR_PROJECT_ID',
    storageBucket: 'YOUR_PROJECT.appspot.com',
    messagingSenderId: 'YOUR_SENDER_ID',
    appId: 'YOUR_APP_ID'
  } as FirebaseOptions
};

Get these values from Firebase Console → Project settings → Your apps → Web app config.

3. Register the library in your app

app.config.ts:

import { ApplicationConfig } from '@angular/core';
import { provideFirestoreKit } from 'ngx-firestore-wrapper-kit';
import { environment } from './environments/environment';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFirestoreKit(environment.firebaseConfig)
  ]
};

4. Usage

Import from the package:

import {
  FirestoreDataService,
  FirestoreResponse
} from 'ngx-firestore-wrapper-kit';

Inject FirestoreDataService where you need Firestore data. It is providedIn: 'root', so no extra providers are required.

Response shape

All listener methods return Observable<FirestoreResponse<T>>:

interface FirestoreResponse<T> {
  success: boolean;
  data: any;      // payload when success is true
  error: unknown; // error when success is false
}

Always check success before using data.

Listen to a document (real-time)

import { inject, OnDestroy, OnInit } from '@angular/core';
import { Subscription } from 'rxjs';
import { FirestoreDataService, FirestoreResponse } from 'ngx-firestore-wrapper-kit';

interface BatchJob {
  status: string;
  progress: number;
}

export class BatchJobComponent implements OnInit, OnDestroy {
  private readonly firestoreData = inject(FirestoreDataService);
  private sub?: Subscription;

  response: FirestoreResponse<BatchJob> | null = null;

  ngOnInit(): void {
    // collection / collection-001 (document) / subCollection / sub-collection-001 (document)
    const path = ['collection', 'collection-001', 'subCollection', 'sub-collection-001'];

    this.sub = this.firestoreData
      .listenToDocument<BatchJob>(path)
      .subscribe((res) => (this.response = res));
  }

  ngOnDestroy(): void {
    this.sub?.unsubscribe();
  }
}

Listen to a collection (real-time)

import { inject, OnDestroy, OnInit } from '@angular/core';
import { Subscription } from 'rxjs';
import { FirestoreDataService, FirestoreResponse } from 'ngx-firestore-wrapper-kit';

interface BatchJob {
  status: string;
  progress: number;
}

export class BatchJobListComponent implements OnInit, OnDestroy {
  private readonly firestoreData = inject(FirestoreDataService);
  private sub?: Subscription;

  response: FirestoreResponse<BatchJob[]> | null = null;

  ngOnInit(): void {
    // collection / collection-001 (document) / subCollection
    const path = ['collection', 'collection-001', 'subCollection'];

    this.sub = this.firestoreData
      .listenToCollection<BatchJob>(path)
      .subscribe((res) => (this.response = res));
  }

  ngOnDestroy(): void {
    this.sub?.unsubscribe();
  }
}

Path helpers

Build paths as string arrays — alternating collection and document IDs:

// Document: collection / {collectionId} (document) / subCollection / {subCollectionId} (document)
const documentPath = ['collection', 'collection-001', 'subCollection', 'sub-collection-001'];

// Collection: collection / {collectionId} (document) / subCollection
const collectionPath = ['collection', 'collection-001', 'subCollection'];

Example with the service:

this.firestoreData
  .listenToDocument<ChildDocument>(documentPath)
  .subscribe((res) => { /* ... */ });

5. Checklist

• [ ] ngx-firestore-wrapper-kit installed
• [ ] Firebase config added to environment.ts
• [ ] provideFirestoreKit(environment.firebaseConfig) in root providers
• [ ] FirestoreDataService injected in components/services
• [ ] Paths passed as string[]
• [ ] Subscriptions unsubscribed in ngOnDestroy (or use async pipe)

Exports reference

| Export | Use | |--------|-----| | provideFirestoreKit(config) | Bootstrap Firebase + Firestore in the app | | FirestoreDataService | listenToDocument(), listenToCollection() | | FirestoreResponse<T> | Type for listener responses |