Getting started

The whole flow, from zero to a notification appearing in your browser, is five steps.

New here? Try it before you wire anything up. Run the full subscribe → push → click loop in your browser first: create your project with tester.litepush.dev as its origin, paste its Project ID + VAPID public key into the hosted tester at tester.litepush.dev, hit Subscribe, and send yourself a push (step 5). Once you've seen it work, unsubscribe in the tester (or delete the test subscriber from the Subscribers tab) so your test device isn't in your real audience — then change the origin to your real domain in Settings → General and drop the SDK into your site (steps 2–4). The tester only subscribes for a project whose origin is tester.litepush.dev — the same origin setting your real site will use.

1. Create your account

Go to litepush.dev/signup and enter your email. We'll send an auth link — no password.

Once you're in, click New project, give it a name (e.g. my-blog), and set the origin to the public hostname where your SDK will run (e.g. myblog.com).

Local development: the API does not accept http://localhost as a project origin. To test the SDK against the API from your device, expose your dev server through a tunnel (e.g. Cloudflare Tunnel or ngrok) and register the tunnel's HTTPS hostname as your project's origin.

You'll see three things on the project's overview page:

• Project ID — prj_xxxxxxxx
• VAPID public key — the public half of the keypair we generated for your project. You can rotate it later from Settings → Rotate VAPID keys, but doing so invalidates every active subscription, so only rotate if the key is compromised or you want a fresh start.
• API key — lpk_live_xxxxxxxx, shown once at creation. Copy it now; we only store the SHA-256 hash and can't recover the plaintext.

2. Drop the SDK into your site

Paste this <script> tag on every page where you want to register subscribers:

<script
  src="https://litepush.dev/sdk.js"
  data-project="prj_xxxxxxxx"
  data-vapid-key="BL9...your-public-key"
  async
></script>

The overview page generates this snippet with your project's values pre-filled — just hit the copy button.

3. Add the service worker

LitePush needs a service worker on your origin to receive push messages while the browser tab is closed. Download the pre-built worker from your project's overview page (or directly at litepush.dev/litepush-sw.js) and serve it at your site root:

https://myblog.com/litepush-sw.js

The SDK auto-registers it for you on first call.

4. Ask the visitor to subscribe

From your page (after a click — browsers require a user gesture):

document.getElementById("subscribe-btn").addEventListener("click", async () => {
  const result = await litepush.subscribe({
    userId: currentUser.id, // optional — your own user id
  });
  if (result) {
    console.log("Subscribed:", result.id);
  } else {
    console.warn("User denied notification permission.");
  }
});

subscribe() returns { id } on success or null if the user denied permission. It throws if the browser doesn't support web push — call litepush.canSubscribe() first if you want to gate the button.

That's it on the client side. You'll see the subscriber appear in your dashboard's Subscribers tab within seconds.

5. Send a notification

From your server (Node / Bun / Deno / anything that can POST):

curl -X POST https://api.litepush.dev/v1/send \
  -H "Authorization: Bearer lpk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "target": { "type": "all" },
    "notification": {
      "title": "New post on the blog",
      "body": "We just shipped Web Push support — read more",
      "url": "https://myblog.com/posts/web-push"
    }
  }'

Response:

{ "broadcast_id": "bdc_01HXM..." }

The notification fans out asynchronously. Watch the broadcast's Delivered counter in the dashboard tick up.

What next?

• Want to target a subset of subscribers? Read /v1/groups.
• Want your server to be notified when a user clicks the push? Read Webhooks.
• Want to integrate from your backend? Start with API concepts.