Laravel Nova Pwa Laravel Package

Getting Started

laravel-nova-pwa adds Progressive Web App plumbing — web app manifest, service worker, installability, and asset caching — to the Nova administration panel. The value is narrow but real: an installable Nova icon on a phone or desktop, faster repeat loads, and a shell that survives flaky connectivity.

Minimal path in a fresh project:

1. composer require sergeich5/laravel-nova-pwa
2. Publish the package config and any front-end assets (php artisan vendor:publish --provider="Sergeich5\LaravelNovaPwa\..." — confirm the exact provider/namespace against the README, it is not stated in the changelog).
3. Open the published config and set at minimum: app name, short name, theme/background colors, and start URL (should point at your Nova path, e.g. /nova).
4. Ensure the app is served over HTTPS in every environment where you expect installability — localhost is the only exception browsers grant.
5. Load Nova in a Chromium browser and check DevTools → Application → Manifest for parse errors, then → Service Workers for a registered, activated worker.

Where to look first: the package config file after publishing, then the service worker it serves (fetch it directly at whatever path the package registers, usually /service-worker.js or a Nova-scoped route). Reading the actual worker source answers most questions about what is cached and when.

First realistic use case: an on-call or field team that needs one-tap access to Nova on a phone without typing a URL and logging in each time. Install the PWA, keep the session alive, and you get an app-like entry point. Treat it as a launcher and a shell cache — not as offline data access.

Also verify the release you are installing: v1.0.4 ships with only a compare link and no described changes. Diff v1.0.3...v1.0.4 yourself before upgrading — for a patch bump the expected content is a manifest/worker tweak or a Nova compatibility fix, but you should confirm nothing touches cache keys or the worker path.

Implementation Patterns

Config-driven branding. Drive the manifest entirely from config so each environment (staging vs production) can carry a different name/short_name/start_url and icons. Do not hand-edit the served manifest — you will lose it on the next publish.

Keep the worker scoped to Nova. Register the service worker at the narrowest scope that covers /nova rather than /. Two reasons: your public marketing site may already run its own PWA worker, and a root-scoped worker from this package will fight it for control of the same pages. If the package registers at root, override the scope in your own registration snippet.

Precache the shell, not the data. The sensible caching strategy for an admin panel is: cache the Nova JS/CSS bundle, fonts, and icons (cache-first with a versioned cache name); leave all /nova-api/* and Nova resource routes network-only. Caching API responses on a shared admin tool is how you leak one user's records into another session on the same device.

Deploy-time cache busting. Tie the service worker cache name to a build identifier — APP_VERSION, a git SHA, or your Nova asset version — so each deploy activates a fresh cache and purges the old one in the worker's activate handler. Without this you will ship a Nova upgrade and half your team will keep running the previous bundle for days.

Pair it with your asset pipeline. If you already run mix/vite with hashed Nova assets, make sure the worker's precache list is generated from the same manifest rather than hardcoded filenames, otherwise every deploy silently 404s a precached file and the install step partially fails.

Session handling. The PWA has no special auth story — it is the same Nova session in a different browser chrome. Set a sensible "remember me" or session lifetime so the installed app does not dump users to the login screen constantly, and make sure your logout flow still works from a standalone window (no address bar to fall back on).

Gotchas and Tips

• HTTPS or nothing. Install prompts, service workers, and the manifest all silently no-op over plain HTTP on non-localhost. If the install banner never appears, check the protocol before you check the config.
• Stale Nova after upgrades is the #1 support ticket. Nova's own Mix/Vite hashed filenames plus an over-eager cache-first worker equals a broken admin UI that only a hard reload fixes. Always bump the cache version on deploy, and document the "clear site data" recovery step for your team.
• Service worker scope conflicts. A worker registered at / will intercept requests for your entire application, including any other PWA. Verify the registration scope in DevTools and narrow it if the package defaults to root.
• Manifest path vs public/. If the package serves the manifest through a Laravel route rather than a static file, CDN/edge caching can serve a stale manifest after you change the app name or icons. Purge the edge cache as part of the deploy.
• Icon requirements are strict. Maskable icons need adequate padding (roughly the inner 80% safe zone) or Android will crop your Nova logo into an unrecognisable square. Supply 192×192 and 512×512 at minimum, plus a maskable variant if you care about the home screen.
• CSP will bite you. A strict Content-Security-Policy needs worker-src (or child-src) to allow the worker script, and the manifest fetch must be permitted by connect-src/default-src. Symptom: silent registration failure with only a console CSP violation and no network error.
• Not an offline app. Unless the package explicitly documents offline data sync — nothing in the v1.0.4 notes suggests it does — assume forms and resource pages require the network. Do not promise offline data entry to stakeholders.
• Debugging workflow: DevTools → Application → Service Workers → "Update on reload" while developing; then test the cold path in an incognito window with the network throttled to Offline to see what actually renders. Unregister the worker after experiments, or you will chase ghosts on the next feature branch.
• Extension point: if the package exposes events or a publishable worker stub, prefer overriding the caching strategy there over patching vendor files — you want to survive the next patch release.
• Version hygiene: with v1.0.4 arriving as a bare compare link, pin the dependency ("sergeich5/laravel-nova-pwa": "1.0.4") and read the diff before bumping. Unexplained patch releases on a package that controls your admin panel's caching deserve a two-minute look, not a blind composer update.