DEV Community

张义
张义

Posted on

Making a booking page installable: tenant-aware PWA with vite-plugin-pwa

A PWA is usually explained with one manifest and one service worker. That's fine until you serve many tenants from one installation — then every tenant needs its own app identity, its own icon label, its own start URL, and none of them should collide.

This post covers the parts that were not obvious: a per-tenant manifest, the id field that prevents duplicate home-screen icons, an update flow that doesn't destroy a half-filled booking form, and what should never be cached.

Setup

Vite 6 with vite-plugin-pwa, Workbox generateSW. The important setting is that the manifest is not generated at build time:

VitePWA({
  registerType: 'prompt',
  manifest: false,        // served by the API, per tenant
  workbox: {
    navigateFallbackDenylist: [/^\/api\//],
    runtimeCaching: []    // no API caching
  }
})
Enter fullscreen mode Exit fullscreen mode

registerType: 'prompt' means a new service worker installs and then waits. It doesn't take over until the app tells it to. More on that below.

Per-tenant manifest

Each tenant has a slug. The booking page fetches its manifest from the API:

@GetMapping(value = "/api/client/manifest", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<Map<String, Object>> manifest(@RequestParam String slug) {
    Tenant t = tenantService.findActiveBySlug(slug);

    Map<String, Object> m = new LinkedHashMap<>();
    m.put("id", "/book/" + slug);                       // stable identity per tenant
    m.put("name", t.getName());
    m.put("short_name", abbreviate(t.getName(), 12));
    m.put("start_url", "/#/book?slug=" + slug);
    m.put("scope", "/");
    m.put("display", "standalone");
    m.put("orientation", "portrait");
    m.put("background_color", "#ffffff");
    m.put("theme_color", t.getThemeColor());
    m.put("icons", List.of(
        icon("/icons/icon-192.png", "192x192", "any"),
        icon("/icons/icon-512.png", "512x512", "any"),
        icon("/icons/icon-maskable-512.png", "512x512", "maskable")
    ));
    return ResponseEntity.ok()
        .cacheControl(CacheControl.noStore())
        .body(m);
}
Enter fullscreen mode Exit fullscreen mode

And in the page:

<link rel="manifest" href="/api/client/manifest?slug=my-salon">
Enter fullscreen mode Exit fullscreen mode

Three details worth calling out:

  • start_url contains the slug, so an installed icon opens that shop, not a generic landing page.
  • scope stays at / because a single installation serves many shops; scoping to the slug would break navigation.
  • The manifest response is no-store. It's cheap to generate and you don't want a stale theme color or a stale start_url cached at the CDN.

The id field, and why you need it

This one cost me a confusing afternoon.

Chrome identifies an installed PWA by its manifest id. If id is absent, Chrome falls back to start_url — and since start_url differs per tenant, each tenant became a separate installable app. Fine, except some of my URLs also changed slightly during a refactor, and the same shop ended up with two icons on the home screen and two entries in the app list.

Setting an explicit, stable id per tenant fixes it. Treat it like a database key: once shipped, never change it, even if routes change.

Update flow that doesn't eat form data

A booking form is exactly the kind of page you must not reload underneath the user.

With registerType: 'prompt', the flow is:

  1. A new service worker installs and moves to waiting.
  2. The app detects waiting and shows a small banner: A new version is available. Reload.
  3. The user finishes what they're doing and taps the button.
  4. Only then: skipWaiting() on the waiting worker, controllerchange fires, reload.
const reg = await navigator.serviceWorker.ready;

if (reg.waiting) {
  showUpdateBanner(() => {
    reg.waiting.postMessage({ type: 'SKIP_WAITING' });
  });
}

navigator.serviceWorker.addEventListener('controllerchange', () => {
  window.location.reload();
});
Enter fullscreen mode Exit fullscreen mode

Two practical notes:

  • Serve sw.js with no-cache, no-store, must-revalidate. Otherwise browsers can hold an old worker for a long time and updates appear to be "stuck".
  • Don't show that banner in embedded iframes. A booking widget lives inside someone else's page; prompting for a reload there is confusing and pointless.

I also gate the prompt to narrow screens and installed display mode. On desktop, a silent activation on the next visit is less disruptive than a banner in the middle of an admin session.

What not to cache

It's tempting to precache everything. Don't.

Resource Cache? Why
index.html, built JS/CSS, icons, fonts Yes App shell should open offline
Availability API No Stale slots cause double bookings
Booking submission No Must fail loudly, never queue silently
My Bookings No Personal data, must be live

The offline experience is therefore: the shell opens, the UI explains that it's offline, and API-backed actions are disabled rather than attempted. That's honest and it's much less work than an offline write queue with conflict resolution.

Install entry

beforeinstallprompt fires early, often once, and only after the browser has decided your site qualifies. If you attach the handler inside a component that mounts later, you'll wonder why the install button never appears.

Capture it at app startup, keep the event, and show the button only when it exists:

let deferredPrompt = null;

window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  deferredPrompt = e;
});
Enter fullscreen mode Exit fullscreen mode

iOS has no equivalent. Safari installs through Share → Add to Home Screen, so show that instruction as text instead of a button. And hide the install entry entirely when the app is already running in standalone mode, or when it's inside an iframe.

Result

The end state: a customer opens a shop link, books in under a minute, and can install that shop as an app that opens straight into its booking page. An operator deploys one container and every tenant gets that behaviour without a build step per tenant.

I build Skeduvo, a self-hosted multi-tenant booking and scheduling system with the customer flow implemented as a PWA — full source code, backend and frontend.

If you've solved the multi-tenant manifest problem differently, I'd like to hear about it.

Top comments (0)