notifkit

Browser notification wrapper — one API for push, toast, and in-app notifications.

Features

• 🎯 One API — notify() handles everything
• 🔔 Browser notifications with automatic permission handling
• 🍞 Toast fallback when browser notifications aren't available
• 📱 Mobile-safe with vibration support
• 🎨 Customizable toast positions and styling
• 🪶 Lightweight — <2KB gzipped
• 🔧 TypeScript first-class support

Installation

npm install @fauzitech/notifkit

Quick Start

import { notify, configure } from '@fauzitech/notifkit';

// Configure once
configure({
  defaultIcon: '/icon.png',
  fallbackToToast: true,
});

// Send notification
notify({
  title: 'Order Ready!',
  body: 'Your order #123 is ready for pickup',
  icon: '/order-icon.png',
  onClick: () => window.location.href = '/orders/123',
});

API

notify(options)

Send a notification. Automatically chooses browser notification or toast fallback.

const result = await notify({
  title: 'Notification Title',     // Required
  body: 'Notification body text',  // Optional
  icon: '/icon.png',               // Optional
  tag: 'order-123',                // Optional grouping
  requireInteraction: false,       // Optional keep-open
  onClick: () => {},               // Optional click handler
  onClose: () => {},               // Optional close handler
  forceToast: false,               // Optional force toast
  toastDuration: 5000,             // Optional toast duration
  toastPosition: 'bottom-right',   // Optional toast position
});

configure(options)

Set global defaults.

configure({
  defaultIcon: '/icon.png',
  defaultToastDuration: 3000,
  defaultToastPosition: 'top-right',
  serviceWorkerPath: '/sw.js',
  autoRequestPermission: true,
  fallbackToToast: true,
});

Permission Helpers

import { 
  isSupported, 
  isPermissionGranted, 
  isPermissionDenied,
  requestPermission,
  getPermissionStatus 
} from '@fauzitech/notifkit';

isSupported();          // true if Notification API available
isPermissionGranted();  // true if permission granted
isPermissionDenied();   // true if permission denied
await requestPermission(); // Request permission
getPermissionStatus();  // 'granted' | 'denied' | 'default' | 'unsupported'

Service Worker

import { registerServiceWorker } from '@fauzitech/notifkit';

await registerServiceWorker('/sw.js');

Toast Management

import { clearToasts } from '@fauzitech/notifkit';

clearToasts(); // Remove all visible toasts

Toast Positions

• top-left
• top-center
• top-right
• bottom-left
• bottom-center
• bottom-right

Browser Support

• Chrome 50+
• Firefox 44+
• Safari 16+ (macOS), 16.4+ (iOS)
• Edge 79+

License

MIT © Muhammad Fauzi Azhar