Push stops losing a notification every time a subscription rotates

[darbymanning]

The gap

pushsubscriptionchange fires only inside a service worker — the one place postboi had no presence at all. postboi shipped subscribe(), push(), push.expired() and the framework subscription() stores, but deliberately no worker, so every app hand-rolled the same three handlers. The one everybody skips is the one that matters: when a browser rotates a subscription, the address you stored is dead, and the gap only closes after a send 410s — one notification silently gone first.

receive() from postboi/push/sw

// src/service-worker.ts
import { receive } from "postboi/push/sw"

receive({ register: "/push/subscriptions" })

Registers all three handlers:

• push — shows what postboi/webpush sent. Never throws: an unparseable payload degrades to a body, because a push handler that throws shows nothing and a browser that sees pushes arrive with no notification revokes the permission.
• notificationclick — focuses the tab already showing that URL instead of opening a duplicate. No url means the send didn't ask for navigation, so nothing happens.
• pushsubscriptionchange — takes Firefox's newSubscription or mints one with the VAPID key bunx postboi sync already bakes, then POSTs the replacement to register with old_endpoint alongside it. Delete that row, store the rest — a swap rather than a leak.

notification: (payload) => ({ … }) merges over the defaults, covering both the app-name fallback and tag/renotify/actions with one hook.

The CLI does the wiring

Of the frameworks this repo ships examples for, only SvelteKit builds a service worker. Next, Nuxt, Astro and Remix serve public/sw.js verbatim, where an import is a syntax error at worker startup with nothing pointing at the cause. So the generated shape isn't a fallback — it's the majority path.

bunx postboi init --push now finds the worker where the framework keeps it, or creates one where that framework expects it, and writes the shape that file can actually run:

Subscriptions expire and browsers rotate them. Only a service worker hears about it.
Create public/sw.js to receive notifications? (Y/n)
  Endpoint a subscription is filed at (/push/subscriptions)

✓ created public/sw.js (handlers written out — this file is served as-is and can't import)

  On the page:
    subscription({ register: "/push/subscriptions" })

Framework	File	Shape
SvelteKit	src/service-worker.ts	Built — imports postboi/push/sw
Next, Nuxt, Astro, Remix	public/sw.js	Served as-is — handlers written out, VAPID key baked in

It refuses to append to a worker that already handles push itself (two handlers is two notifications per send) and re-running is a no-op. The page snippet it prints names service_worker whenever the worker isn't at /sw.js — the most common way a fully wired setup still answers no_service_worker.

Keeping the two copies honest

Two implementations of one behaviour is exactly the arrangement that drifts, so src/testing/worker.ts is a vitest-free fake worker that both are driven through — receive() with the fake installed as globals, the generated source with it passed as self — and their recordings compared. A change made to one and not the other fails that test. Mutation-checked: dropping the focus-existing-tab lookup from the generated copy fails it.

Also verified against real temp project layouts on disk (Next with public/, SvelteKit with tsconfig.json, an Astro project with a conflicting handler, a bare directory), plus node --check on every generated file.

Two contract fixes carried along

• PushPayload in push/types.ts now types both ends of the wire contract — webpush.ts's payload() and the worker reading it. That payload travels as opaque encrypted bytes, so a field-name disagreement surfaces as a notification that never appears rather than an error.
• to_json in push/client.ts became the exported subscription_json, so a rotation is re-filed in exactly the shape the page filed the first one.

Examples

All five move to the generated worker. SvelteKit's stays on static/sw.js rather than the bundled import: the examples bun install postboi from npm, so postboi/push/sw only resolves once this ships. Flipping it is a two-line job for the post-release "Examples: catch up" commit, and it's what gives the docs a runnable example of the import path.

Checks

• 24 new tests, 795 passing
• bun run check — 0 errors
• bun run lint — clean
• build:cli bundles
• svelte-package emits dist/push/sw.{js,d.ts}; publint clean

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	postboi	5e06d79	Commit Preview URL Branch Preview URL	Aug 19 2026, 04:01 PM

[darbymanning]

Examples now build against the commit under test

Pushed as a second commit. The Examples job packs the tarball from the branch and installs that into each example, instead of resolving the ^0.35.0 pins.

npm pack rather than bun link, deliberately — it runs prepack and honours files and exports exactly as npm publish does, so the signal the job was really carrying (a path missing from files, a broken exports entry, a .d.ts that doesn't resolve in someone else's project) still fails here. A symlink would have tested none of that, and would resolve peers from this repo's node_modules rather than the example's.

Verified end to end before committing: packed the tarball, installed it into a copy of the SvelteKit example with bun add, and ran that example's own ci — svelte-check passes on import { receive } from "postboi/push/sw", an API that doesn't exist on npm.

So the thing held back in the original PR is now in: SvelteKit's example moves to the bundled src/service-worker.ts with the real import, and the docs' "runnable example" link demonstrates the import path rather than only the generated one. static/sw.js is gone from that example; the other four stay on the generated public/sw.js, which is correct for them.

RELEASING.md Part C is rewritten to match — bumping the pins is now tidiness (it's what someone copying a folder installs) rather than a release blocker, and the local repro loop is spelled out since a plain bun install in an example resolves the pin instead.

[darbymanning]

One-click releases

Third commit. Actions → Release → Run workflow → type X.Y.Z (or patch/minor/major). No clean local main, no tag-push permission.

It runs scripts/release.sh rather than a copy of it — the script stays the single implementation of the preconditions, bump, validation and commit, and the workflow is just a machine that always has a clean checkout.

The one difference is the tag. GitHub deliberately doesn't run workflows for refs pushed with the automatic token, so a tag pushed from inside Actions would land and nothing would publish. The workflow sets RELEASE_SKIP_TAG=1, pushes only the bump commit, and dispatches Publish — whose existing workflow_dispatch path already derives the tag from package.json and creates it. That route existed for sandboxes that can't push tags; this makes it the one Actions uses.

Nothing here publishes. publish.yml is still the only thing that talks to npm, and it re-runs the full suite first — so a release started by mistake is stopped by a red test rather than by someone catching it in time.

Both branches exercised against a throwaway repo with a local bare origin before committing: CI mode bumped, committed, pushed and created no tag locally or on the remote; the local path still tags and pushes both, unchanged.

---

Worth saying explicitly: this is not publish-on-merge, which I'd argue against for this repo. Nothing in a merge says patch vs minor — the commit style is prose, not conventional commits, and pre-1.0 "breaking changes are minor" is a judgement call. The docs snapshot in part A has ordering baked in that a merge can't satisfy. And docs-only merges would publish, since the site already deploys on push to main.

If you want to go further later, the next step is the release-PR pattern: PRs declare their bump, a workflow opens a "Release 0.36.0" PR carrying the bump and the docs snapshot, and merging that publishes. That makes the snapshot a reviewable diff, which is the step that most deserves eyes. This commit doesn't foreclose it.