PushBase Web SDK

The PushBase Web SDK will provide browser-based push notifications using Firebase Cloud Messaging, bringing the same powerful and simplified API to web applications.

Overview

The PushBase Web SDK wraps Firebase Cloud Messaging (FCM) for the browser with automatic Service Worker management, permissions, token handling, and message processing. It supports:

FCM setup via firebaseConfig and VAPID key
Auto or manual SDK initialization
Foreground message listeners, token refresh, and error handling
Push subscription metadata via subscribe()
Typed configuration and state helpers

Expected Installation

npm install @pushbase/web

Service Worker Setup

Default service worker path is /firebase-messaging-sw.js.
Ensure a service worker file is available at your app’s public root. You can start from the default template and customize as needed.
If your file lives elsewhere, set serviceWorkerPath in config.

Quick Start

import { PushBaseWeb } from "@pushbase/web";

// First call to getInstance must include config
const pushBase = PushBaseWeb.getInstance({
  firebaseConfig: {
    apiKey: "your-api-key",
    authDomain: "your-project.firebaseapp.com",
    projectId: "your-project-id",
    storageBucket: "your-project.appspot.com",
    messagingSenderId: "123456789",
    appId: "your-app-id",
  },
  vapidKey: "your-vapid-key",
  debug: import.meta.env.DEV,
  // serviceWorkerPath: '/firebase-messaging-sw.js', // default
  // autoInitialize: true (default)
});

// Optional: explicit init if autoInitialize: false
await pushBase.initialize();

// Permissions + token
const permissions = await pushBase.requestPermissions();
if (permissions.granted) {
  const token = await pushBase.getToken();
  console.log("FCM token:", token);
}

Alternatively, use the convenience helper:

import { createPushBaseWeb } from "@pushbase/web";

const pushBase = createPushBaseWeb({
  firebaseConfig,
  vapidKey,
  debug: true,
});

Foreground Messages and Events

// Foreground messages
const unSubMsg = pushBase.onMessage((message) => {
  console.log("Foreground message:", message);
});

// Token refresh
const unSubToken = pushBase.onTokenRefresh((token) => {
  console.log("Token refreshed:", token);
});

// Errors
const unSubErr = pushBase.onError((error) => {
  console.error("PushBaseWeb error:", error);
});

Push Subscription Data

// Returns endpoint/keys (useful for your server, Web Push workflows)
const subscription = await pushBase.subscribe();
console.log("Subscription:", subscription);
/*
{
  endpoint: string,
  keys: { p256dh: string, auth: string },
  token?: string,
  userAgent?: string,
  timestamp: number
}
*/

State and Lifecycle

const state = pushBase.getState();
const hasPermissions = await pushBase.hasPermissions();

// Cleanup
pushBase.destroy();

Types

import {
  PushBaseWebConfig,
  WebPushMessage,
  WebPermissionStatus,
  WebSDKState,
  PushSubscriptionData,
} from "@pushbase/web";

Notes:

The SDK auto-registers the service worker using serviceWorkerPath (default /firebase-messaging-sw.js).
You can customize defaultNotificationOptions in config (icon, badge, etc.).

Web SDK

On this page