@mindinventory/mi-quick-fcm-push-notification

v1.0.0

Published

5 days ago

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

Web Push Notification

Firebase push notifications for React and Next.js — set up in one command

Web Push Notification is a CLI tool that scaffolds Firebase Cloud Messaging (FCM) push notification infrastructure for React and Next.js projects. It detects your framework, router type, and language — then generates the files your project needs.

What it does

Framework detection — Detects React vs Next.js (App Router / Pages Router) from your package.json. Exits cleanly if the project is unsupported.
TypeScript and JavaScript — Generates .ts/.tsx for TypeScript projects and .js/.jsx for JavaScript projects
No .env file needed — Firebase values go into mi-quick-fcm-push-notification.config.json and are imported directly — works across React, Next.js, and Vite with no prefix changes
Next.js support — Generates a 'use client' PushProvider wrapper for your layout.tsx
Auto install — Installs firebase and mi-quick-fcm-push-notification into the target project before scaffolding if they are missing
Backend scaffolding — Generates FCMHelper and register/unregister routes for Express and NestJS
Safari 16+ support — Works with the same VAPID key as Chrome and Firefox — no extra Apple setup needed

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

1. Run init

npx @mindinventory/mi-quick-fcm-push-notification init

The CLI will:

Detect your framework and language
Install firebase and mi-quick-fcm-push-notification into your project if missing
Ask for your Firebase config values
Store them in mi-quick-fcm-push-notification.config.json (added to .gitignore automatically)
Generate files in NotificationHandler/ (inside src/ if your project uses one)
Next.js only: generate a PushProvider component in components/ ready to drop into your layout

2. Wrap your app

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

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

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

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

import { CustomPushProvider } from '@mindinventory/mi-quick-fcm-push-notification';
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

import { usePushMessage } from '@mindinventory/mi-quick-fcm-push-notification';

function NotifyButton() {
  const { requestPermission, token } = usePushMessage();
  return (
    <button onClick={() => requestPermission()}>
      {token ? 'Notifications on' : 'Enable notifications'}
    </button>
  );
}

Check NotificationHandler/USAGE.md (generated in your project) for a full copy-pasteable example.

Safari support

Safari 16+ on macOS and iOS 16.4+ support Web Push using the same standard as Chrome and Firefox:

No Apple certificate needed — the VAPID key from Firebase is all you need
User gesture required — requestPermission() must be called from a button click. Calling it automatically on page load will silently fail in Safari
iOS — only works when your site is installed as a PWA (Share → Add to Home Screen). Regular iOS Safari browser does not support push
The generated service worker uses clients.openWindow() as the click navigation fallback, which is the reliable method across all Safari versions

Config

Firebase values are stored in mi-quick-fcm-push-notification.config.json and imported directly by the generated config.ts / config.js:

import pkg from '../../mi-quick-fcm-push-notification.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 mi-quick-fcm-push-notification.config.json. No need to re-run the CLI.

`usePushMessage` hook

| Property | Type | Description | |----------|------|-------------| | token | string \| null | The FCM device token | | messages | PushMessage[] | Foreground notifications received in this session | | 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 button click for Safari) | | sendMessage | (title, body, data?) => Promise<void> | Sends a push via your configured backend | | clearMessages | () => void | Clears the local messages array |

Backend scaffolding

The CLI generates an FCMHelper in src/helper/ using the Firebase Admin SDK:

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 a backend-only setup (no React/Next.js frontend):

npx @mindinventory/mi-quick-fcm-push-notification init --backend-only

Other CLI commands

# Generate only the service worker file
npx @mindinventory/mi-quick-fcm-push-notification generate-service-worker

# Generate standalone files (no mi-quick-fcm-push-notification runtime import)
npx @mindinventory/mi-quick-fcm-push-notification init --files

Documentation

Installation Guide — Requirements, Firebase setup, file structure
API Reference — Full CLI, frontend, and backend API docs
Examples — Next.js, React, JavaScript, and backend examples
FAQ — Common questions
Troubleshooting — Error messages and fixes

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme