Installation

Install the package

npm install nudgr

Requirements

• A Nudgr project with an API key (nk_...)
• A public HTTPS site
• A service worker file served from your own origin
• A browser with Push API support

Basic setup

import { Nudgr } from "nudgr";

const nudgr = new Nudgr({
  apiKey: "nk_...",
});

Then subscribe the current user:

await nudgr.subscribe();

Simplest setup

The package ships a ready-to-use service worker implementation at nudgr/sw.

Put that file somewhere your site serves static assets, then point the SDK at that URL.

If you do not already have your own service worker, the current simplest approach is:

• take the built file from node_modules/nudgr/dist/nudgr-sw.mjs
• copy it to a URL your site serves, such as /nudgr-sw.mjs or /push/nudgr-sw.mjs

Example destination:

/nudgr-sw.mjs

Custom swPath and swScope

If you want to isolate Nudgr from other service workers, use a dedicated sub-path:

const nudgr = new Nudgr({
  apiKey: "nk_...",
  swPath: "/push/nudgr-sw.mjs",
  swScope: "/push/",
});

Recommended mental model:

• swPath: where the browser downloads the service worker file
• swScope: which URL space that service worker controls

Use a dedicated path if:

• you already have another service worker
• you want to reduce scope conflicts
• you only need Nudgr on part of the site

Existing service worker

If your app already has a service worker, you usually should not create a second overlapping root worker.

Instead:

• keep your existing service worker file
• import nudgr/sw inside that file
• point swPath at your existing worker URL

See Service Worker for the exact pattern.

Why the service worker must be served from your own origin

The SDK registers a browser service worker with:

navigator.serviceWorker.register(swPath, { scope: swScope });

That means the browser must be able to fetch a real service worker file from your site, such as:

• /nudgr-sw.mjs
• /push/nudgr-sw.mjs

This is why node_modules/nudgr/dist/nudgr-sw.mjs is not enough by itself. node_modules is a build-time path, not a browser URL.

Before you continue

• Use Quick Start for the shortest end-to-end path
• Use SDK API for option and method details
• Use Service Worker for swPath, swScope, and existing SW integration