quick-fcm

v1.12.0

Published

7 days ago

All-in-one push notification package — npm library + CLI scaffolder with Safari support

0High
0Medium
0Low

dushyant6194

firebase push-notifications react fcm web-push safari vapid service-worker cli scaffolder nestjs express QuickFCM

QuickFCM CLI

Production-grade push notifications for React and Next.js — one command, zero guesswork

QuickFCM is a production-grade CLI tool that scaffolds secure Firebase Cloud Messaging (FCM) infrastructure for React and Next.js projects. It detects your framework, router type, and language automatically — then generates the exact files your project needs, correctly wired to quickfcm.config.json.

Features

Framework Detection — Detects React vs Next.js (App Router / Pages Router) automatically. Exits cleanly if the project is unsupported.
JS + TS Support — Generates .ts/.tsx for TypeScript projects and .js/.jsx for JavaScript projects
Zero-Config Frontend — Scaffolds a ready-to-use NotificationHandler/ directory with provider, hook, and config wired up
Direct Config — Firebase values are stored in quickfcm.config.json and read directly — no .env, no prefix headaches (VITE_, REACT_APP_, NEXT_PUBLIC_)
PushProvider for Next.js — Generates a 'use client' PushProvider wrapper in components/ so your layout.tsx stays a Server Component
Auto Dependency Install — Installs firebase and quick-fcm into the target project before scaffolding if they are missing. Uses your existing package manager (pnpm / yarn / npm)
Backend Scaffolding — Generates production-grade FCMHelper and routes for Express / NestJS
Safari Support — Full Safari 16+ Web Push support with proper user-gesture permission flow
App Router Compatible — All client components include 'use client' directives

Supported Projects

| Project type | Supported | |---|---| | React (TypeScript) | ✓ | | React (JavaScript) | ✓ | | Next.js App Router (TS or JS) | ✓ | | Next.js Pages Router (TS or JS) | ✓ | | Vite + React | ✓ | | Express / NestJS backend | ✓ (via --backend-only) | | Plain Node.js (no React/Next.js) | ✗ — CLI exits with a clear message |

Quick Start (3 Minutes)

1. Initialize

npx quick-fcm init

The CLI will:

Auto-detect your framework (React / Next.js App Router / Next.js Pages Router)
Install firebase and quick-fcm into your project if missing
Ask for your Firebase config values
Store them in quickfcm.config.json (no .env needed — works across React, Next.js, and Vite with zero prefix changes)
Generate files in NotificationHandler/ (inside src/ if your project uses one) using the right extension (.ts/.tsx or .js/.jsx — detected from your project)
Next.js only: generate PushProvider (.tsx/.jsx/.js depending on your project) — a 'use client' wrapper ready to drop into your layout

2. Wrap your application

Next.js (app/layout.tsx) — use the generated PushProvider:

import { PushProvider } from '@/components/PushProvider'; // generated

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <PushProvider>
          {children}
        </PushProvider>
      </body>
    </html>
  );
}

React (src/App.tsx or src/main.tsx) — wrap with CustomPushProvider directly:

import { CustomPushProvider } from 'quick-fcm';
import { pushConfig } from './NotificationHandler/config';
import { PushNotificationManager } from './NotificationHandler/PushNotificationManager';

function App() {
  return (
    <CustomPushProvider config={pushConfig}>
      <PushNotificationManager />
      <YourApp />
    </CustomPushProvider>
  );
}

3. Enable notifications from a button

Check NotificationHandler/USAGE.md (generated by the CLI inside your project) for a copy-pasteable permission button example.

Config

Firebase values are stored in quickfcm.config.json and imported directly by the generated config.ts/config.js — no .env, no prefix changes needed across React, Next.js, or Vite.

The generated NotificationHandler/config.ts (path depends on whether your project uses src/) looks like:

import pkg from '../../quickfcm.config.json';

export const pushConfig = {
  apiKey:            pkg.firebase.apiKey,
  authDomain:        pkg.firebase.authDomain,
  projectId:         pkg.firebase.projectId,
  storageBucket:     pkg.firebase.storageBucket,
  messagingSenderId: pkg.firebase.messagingSenderId,
  appId:             pkg.firebase.appId,
  vapidKey:          pkg.firebase.vapidKey,
};

To update credentials, edit quickfcm.config.json. quickfcm.config.json is automatically added to .gitignore.

The usePushMessage hook provides the complete interface:

| Property | Type | Description | |----------|------|-------------| | token | string \| null | The unique FCM device token | | messages | PushMessage[] | Array of foreground notifications received | | isSupported | boolean | Whether the browser supports Web Push | | isPermissionGranted | boolean | Current notification permission status | | requestPermission | () => Promise<boolean> | Triggers the browser permission prompt (must be called from a click handler for Safari) | | sendMessage | (title, body, data?) => Promise<void> | Sends a push via your configured backend | | clearMessages | () => void | Clears the local messages state |

Backend Scaffolding

The CLI generates a high-performance FCMHelper in src/helper/:

import { sendPushNotification } from './helper/FCMHelper';

await sendPushNotification({
  token: 'user-device-token',
  title: 'Order Shipped!',
  body: 'Your package is on its way.',
  route: '/orders/123',
  icon: '/icons/shipping-192.png'
});

For backend-only setup (Express / NestJS without any frontend):

npx quick-fcm init --backend-only

Configuration

All local configuration is stored in quickfcm.config.json (generated by the CLI):

{
  "stack": {
    "language": "typescript",
    "scope": "both",
    "backendFramework": "express",
    "isNextJs": true,
    "nextRouterType": "app"
  },
  "firebase": { "apiKey": "...", "vapidKey": "..." },
  "backend": { "registerUrl": "http://localhost:3000/push/register" }
}

Documentation

Installation Guide - Requirements, Firebase setup, and detection details
API Reference - Full CLI, frontend, and backend API docs
Examples - Next.js, React, JavaScript, and backend examples
FAQ - Common questions and troubleshooting

License

Made with ❤️ for the React & Node.js communities