Lerix Web Push SDK

Browser push notifications for Lerix — no Firebase, no OneSignal, just VAPID (Web Push standard), matching the same Lerix.notifications.* API the Flutter SDK already has.

1. Install

npm install @lerix-dev/lerix-js

Or drop the pre-built script directly into a page with no build step:

<script src="https://unpkg.com/@lerix-dev/lerix-js/dist/lerix.global.js"></script>

2. Copy the service worker

Web Push requires a service worker file served from your site's own origin — copy node_modules/@lerix-dev/lerix-js/sw/lerix-sw.js to your site's public root so it's reachable at https://yoursite.com/lerix-sw.js (or any path; you pass it to subscribe() if it's not at the default).

The SDK registers it on its own /lerix/ scope, so it works alongside any service worker your app already has at / (a PWA, next-pwa, Workbox).

3. Generate a Web Push key

From the dashboard: Notifications → Settings → Web Push → Generate keys. This is a one-click step — Lerix generates and stores the key pair for you; there's nothing to copy into your code.

4. Use it

import { Lerix } from "@lerix-dev/lerix-js";

Lerix.init({
  apiKey: "your-api-key",
  projectId: "your-project-slug",
});

await Lerix.notifications.init();

Lerix.notifications.setOnNotificationReceived((payload) => {
  // Fired while a tab is open.
  console.log(payload.title, payload.body);
});

Lerix.notifications.setOnNotificationTapped((payload) => {
  // Fired when the user clicks the notification — including one that
  // opened the page from a fully closed tab.
  const screen = payload.metadata.screen;
});

// Prompts for permission and subscribes this browser.
const deviceId = await Lerix.notifications.subscribe();
// `deviceId` is what you pass in `deviceTokens` when sending a notification
// to this browser specifically, from the dashboard or the REST API.

// After login: link this browser to your own user id, so your server can send
// to `externalUserIds` and reach every device that user is signed in on.
await Lerix.setUser(user.id, { identityHash }); // identityHash only if verification is on
// On logout:
await Lerix.clearUser();

identityHash is hex(HMAC-SHA256(identity secret, externalId)), computed by your backend. The id is stored locally and re-sent if this browser registers a new Lerix user.

API

| Method | Description | |---|---| | Lerix.init(config) | Configures the SDK. Call once. | | Lerix.notifications.init() | Registers this app/user with the backend. Call before anything else on notifications. | | requestPermission() | Prompts for notification permission. Returns true if granted. | | checkPermissionStatus() | "granted", "denied", "default", or "unsupported". | | subscribe(swPath?) | Registers the service worker and subscribes to push. Returns the device id. | | getDeviceId() | The device id from the last subscribe() call, if any. | | setOnNotificationReceived(cb) | Fired while a tab is open. | | setOnNotificationTapped(cb) | Fired on click — delivered reliably even from a closed-tab tap. | | setUser(externalId, { identityHash? }) | Links this browser to your own user id (also Lerix.setUser). Safe before init(). | | clearUser() | Unlinks this browser from its user (also Lerix.clearUser). | | getExternalUserId() | The id passed to setUser, or null. |

Browser support

Chrome, Firefox, and Edge support Web Push fully. Safari requires macOS 13+ / iOS 16.4+ — older Safari doesn't support the standard at all.