Vibe Message SDK

Lightweight JavaScript SDK for web push notifications - A modern Firebase Cloud Messaging alternative.

Installation

npm install vibe-message

Usage

1. Initialize Service Worker

Run the following command in your project directory (e.g., in your React/Vite/Next.js frontend):

npx vibe-message init

This will automatically detect your public directory and generate the required push-sw.js file necessary for handling background notifications.

2. Initialize SDK

import { initNotificationClient } from 'vibe-message';

const client = initNotificationClient({
  baseUrl: 'https://your-backend.com/api',
  appId: 'your-app-id',
  publicKey: 'your-public-key'
});

3. Register Device

// When user logs in
await client.registerDevice({
  externalUserId: 'user-123',
  serviceWorkerPath: '/push-sw.js' // optional, defaults to '/push-sw.js'
});

4. Listen for Messages

// Foreground messages (when app is visible)
client.onMessage((payload) => {
  console.log('Message received:', payload);
  // Show in-app notification
});

// Background messages (when notification is clicked)
client.onBackgroundMessage((payload) => {
  console.log('Notification clicked:', payload);
});

// Silent messages (no UI)
client.onSilentMessage((data) => {
  console.log('Silent message:', data);
});

5. Unregister Device

// When user logs out
await client.unregisterDevice('user-123');

API Reference

initNotificationClient(options)

Initialize the notification client.

Parameters:

• options.baseUrl (string): Base URL of your backend API
• options.appId (string): Your app ID from the admin panel
• options.publicKey (string): Your app's public key

Returns: NotificationClient

client.registerDevice(options)

Register a device for push notifications.

Parameters:

• options.externalUserId (string): Your app's user ID
• options.serviceWorkerPath (string, optional): Path to service worker file

Returns: Promise<void>

client.unregisterDevice(externalUserId)

Unregister a device from push notifications.

Parameters:

• externalUserId (string): Your app's user ID

Returns: Promise<void>

client.onMessage(callback)

Register a callback for foreground messages.

Parameters:

• callback (function): Function to handle message payload

client.onBackgroundMessage(callback)

Register a callback for background messages (notification clicks).

Parameters:

• callback (function): Function to handle message payload

client.onSilentMessage(callback)

Register a callback for silent messages.

Parameters:

• callback (function): Function to handle message data

Features

• 🚀 Lightweight - Minimal dependencies, small bundle size
• 🔒 Secure - VAPID authentication, encrypted push
• 📱 Cross-platform - Works on all modern browsers
• 🎯 Type-safe - Full TypeScript support
• 🔄 Background sync - Receive notifications when app is closed
• 🎨 Customizable - Full control over notification appearance

Browser Support

• Chrome/Edge 50+
• Firefox 44+
• Safari 16+ (macOS 13+, iOS 16.4+)
• Opera 37+

License

MIT