browser-web-push

Fullstack Web Push SDK

A complete fullstack TypeScript SDK for implementing web push notifications in your applications. This library provides both client-side (browser) and server-side (Node.js) functionality in a single package.

✨ Built-in Server-Side Functionality

This SDK includes native server-side support with setVapidDetails and sendNotification functions built into the core library - no need for external dependencies!

Installation

npm install browser-web-push

Quick Start

Client-Side Usage (Browser)

import { createWebPushSDK } from 'browser-web-push';

// Initialize the client SDK
const webPushSDK = createWebPushSDK({
    vapidPublicKey: 'your-vapid-public-key'
});

// Subscribe user to push notifications
const subscription = await webPushSDK.subscribeUser();
console.log('User subscribed:', subscription);

Server-Side Usage (Node.js)

import { createServerWebPushSDK, ServerWebPushSDK } from 'browser-web-push';

// Generate VAPID keys (do this once)
const vapidKeys = ServerWebPushSDK.generateVAPIDKeys();

// Initialize server SDK
const serverSDK = createServerWebPushSDK({
    vapid: {
        subject: 'mailto:[e-mail]',
        publicKey: vapidKeys.publicKey,
        privateKey: vapidKeys.privateKey
    }
});

// Send notification
const result = await serverSDK.sendNotification(subscription, {
    title: 'Hello World',
    body: 'Your first push notification!'
});

Legacy API Compatibility

import { webpush } from 'browser-web-push';

// Works exactly like the popular 'web-push' library
webpush.setVapidDetails(
    'mailto:[e-mail]',
    publicKey,
    privateKey
);

const result = await webpush.sendNotification(subscription, payload);

Features

✅ Client-Side (Browser)

• 🌐 Service worker registration and management
• 📱 Push subscription handling
• 🔐 VAPID key validation
• 🎯 Browser compatibility detection

✅ Server-Side (Node.js)

• 🔑 VAPID key generation and management
• 📤 Send push notifications (sendNotification)
• 🔧 Configure VAPID details (setVapidDetails)
• 📊 Bulk notification sending
• 🔍 Subscription validation
• 🌍 Multi-push service support (FCM, Mozilla, etc.)

✅ Fullstack Integration

• 🔄 Seamless client-to-server workflow
• 📝 Shared TypeScript types
• ⚡ Single dependency for both environments
• 🛠 Built-in error handling

API Reference

Client SDK

// Create client SDK instance
const sdk = createWebPushSDK(config: SDKConfig);

// Check if push is supported
sdk.isPushSupported(): boolean

// Subscribe user
sdk.subscribeUser(): Promise<SubscriptionData>

// Unsubscribe user
sdk.unsubscribeUser(): Promise<boolean>

Server SDK

// Create server SDK instance
const sdk = createServerWebPushSDK(config: ServerSDKConfig);

// Generate VAPID keys
ServerWebPushSDK.generateVAPIDKeys(): VAPIDKeys

// Set VAPID details
sdk.setVapidDetails(subject: string, publicKey: string, privateKey: string): void

// Send notification
sdk.sendNotification(subscription: PushSubscription, payload?: NotificationPayload): Promise<SendResult>

// Bulk send
sdk.sendNotificationBulk(subscriptions: PushSubscription[], payload?: NotificationPayload): Promise<BulkSendResult>

// Validate subscription
sdk.validateSubscription(subscription: PushSubscription): boolean

Browser Usage

For browser environments, use the UMD build:

<script src="https://unpkg.com/browser-web-push/dist/browser-web-push.min.js"></script>
<script>
  const sdk = BrowserWebPush.createWebPushSDK({
    vapidPublicKey: 'your-vapid-public-key'
  });
</script>

Examples

See the examples/ directory for complete implementation examples:

• examples/fullstack-usage-example.ts - Complete fullstack example
• examples/vapid-initialization-example.ts - VAPID setup

Requirements

• Node.js: >= 14.0.0
• TypeScript: >= 4.5.0 (for TypeScript projects)
• Modern browsers with service worker support

License

ISC

Support

• 📚 Documentation
• 🐛 Issues
• 💡 Feature Requests

---

Built with ❤️ for the JavaScript community