Pwa Bundle Laravel Package

Getting Started

Framework reality check first. spomky-labs/pwa-bundle is a Symfony bundle, not a Laravel package. You cannot composer require it into a Laravel app and register a service provider — it depends on Symfony's DI container, config/bundles.php, tagged services, and the Symfony routing/config stack. In a Laravel codebase you have two viable paths:

1. Borrow the patterns (recommended): config-driven manifest, single-source icon generation, manifest served from a route, service worker registration wiring. Reimplement in ~100 lines of Laravel, or use vite-plugin-pwa / silviolleite/laravel-pwa.
2. Only if you're in a Symfony app (or a monorepo where you own a Symfony service): composer require spomky-labs/pwa-bundle, enable PwaBundle in config/bundles.php, then work entirely out of config/packages/pwa.yaml.

Where to look first (Symfony install):

• config/packages/pwa.yaml after bin/console config:dump-reference pwa — the manifest: block is the core; everything else is icons, favicons, and service worker wiring.
• bin/console list pwa — the bundle ships a generate command; run it in a deploy step, not per-request.
• The routes it registers (manifest JSON + service worker script) — check bin/console debug:router | grep -i pwa.

First use case: define name, short_name, start_url: /, display: standalone, theme_color, background_color, and point icons at one high-res source image; let the bundle generate the size matrix; add the <link rel="manifest"> tag to your layout head; verify under Chrome DevTools → Application → Manifest.

Implementation Patterns

• Generate at build time, not request time. Run the bundle's generate command in CI/deploy so the manifest, icons, and service worker land in public/ as static assets. Deterministic output, cacheable by CDN, zero runtime cost.
• Route-served manifest for dynamic cases. When you need per-tenant, per-locale, or per-environment manifests, serve it from a controller/route instead of a static file and cache the response (Cache::remember) rather than rebuilding on every hit.
• Icons from one source. Keep a single 512×512+ source PNG/SVG in the repo and generate every size from it. Include a purpose: maskable icon for Android — omitting it is the most common cause of a "broken" installed icon.
• Split responsibilities for the service worker. Let the bundle handle registration and asset plumbing; write your caching/routing strategies yourself in a plain JS file under assets/, then ship it through Vite so it gets hashed and versioned.
• Cache-bust aggressively. Service worker files are cached by browsers for up to 24h regardless of your HTTP headers. Register with updateViaCache: 'none' or register a versioned URL (/sw.js?v=<build-hash>). Same for the manifest — a stale manifest is invisible until someone reinstalls.
• Localization. Manifest values are run through the Symfony translator when it's present, so you can use translation keys in pwa.yaml. Pair this with a locale-aware manifest route if you ship multiple languages.
• Laravel equivalent. vite-plugin-pwa covers service worker + Workbox caching; pair it with a Route::get('/manifest.webmanifest') returning a cached array from config/pwa.php. That gets you 90% of this bundle's value with no Symfony dependency.

Gotchas and Tips

• 1.5.14 change to watch: when symfony/translation is absent, the bundle now falls back to the raw string instead of failing. Practical consequence — if your pwa.yaml uses translation keys (e.g. name: pwa.manifest.name) and the translator isn't installed, you will silently get "name": "pwa.manifest.name" in the output. No exception, no warning. If a manifest looks wrong after upgrading, check this first.
• 1.5.14 is a patch release — no breaking changes, no deprecations, no new features. Pin ^1.5 and, if you rely on translated manifest fields, diff the generated manifest.json before and after the bump.
• Service worker scope trap: a worker served from /pwa/service-worker.js only controls /pwa/, not the site root. Serve it from / or set the Service-Worker-Allowed response header to the desired scope.
• HTTPS or localhost only. Service workers and install prompts silently do nothing over plain HTTP or via a LAN IP. This burns hours on device testing.
• iOS ignores manifest icons for the home screen — you still need apple-touch-icon link tags. Confirm the favicon/webkit generation actually emitted them.
• MIME type pedantry: serve the manifest as application/manifest+json. Chrome tolerates application/json; some tooling and validators don't.
• Deploy pipeline is the real failure mode. Generated files in public/ get stale when the generate command is skipped on deploy. Either commit them or make generation a hard prerequisite of the build — don't leave it to a developer's memory.
• Debugging toolkit: Chrome DevTools → Application (Manifest + Service Workers), chrome://serviceworker-internals to force-unregister a wedged worker, and a Lighthouse PWA audit for installability. "Update on reload" in DevTools should be on during development.
• Extension points (if you're actually on Symfony): the bundle's services are normal container services — override the manifest factory or icon generator via a compiler pass or service decoration rather than forking. In Laravel, there's no equivalent seam; keep your manifest as a plain array in a config file so it's still swappable.