PWA install & icons

Pitchbar ships as a Progressive Web App so admins can install the dashboard to their home screen and run it like a native app. The install prompt appears automatically in supported browsers (Chrome, Edge, Safari iOS 16.4+, Brave) once the page meets the install criteria — usually after a few seconds on the dashboard.

Manifest endpoint

The Web App Manifest is served dynamically at /manifest.webmanifest by App\Http\Controllers\PwaManifestController so the white-label cascade (site title, favicon) flows into the install prompt — operators rebranding the site never ship "Pitchbar" to home-screen labels.

start_url is /dashboard

The installed app opens to /dashboard:

• Unauthenticated installers — Fortify redirects to /login.
• Authed admin with no workspace yet — the dashboard renders an empty state.
• Authed admin with a workspace — Inertia renders the live dashboard.

Client report 2026-05-25: start_url was previously /app, which has no bare route. Installed PWAs opened to a 404 and the service worker cached the 404 shell until the next SW version bump. Fixed by repointing to /dashboard and rolling the SW VERSION constant in public/sw.js.

App icon comes from Settings → Branding → Favicon

When an operator uploads a favicon under /settings/branding, the manifest prepends it as a generic any-sized icon so the install prompt uses that brand mark. The bundled icon-192.png and icon-512.png placeholders stay behind it so installers that demand exact PNG sizes still match.

User-uploaded favicons are NOT tagged purpose=maskable — they aren't safe-zone designed, so Android's adaptive-icon mask would crop the corners badly. The bundled placeholders are purpose-built for maskable use and stay tagged that way.

Bumping the service worker version

public/sw.js has a top-level VERSION constant (e.g. pitchbar-shell-v2). When you change anything about the install behaviour or shell caching, bump the suffix — the activate handler deletes every cache that doesn't start with the new VERSION, so existing installs purge stale assets on next visit.

Cache strategy

• Shell HTML (Inertia routes) — network-first with a 4-second timeout, falling back to last-known cache so a flaky-mobile-data operator still sees something.
• Vite bundles under /build/* — cache-first (URLs are content-hashed; hash rolls every deploy).
• Icons / manifest — cache-first.
• Mutation endpoints (POST/PATCH/DELETE) and /api/v1/widget/* — network-only, never cached.