Skip to content

Configuration ​

All options live in config/pwa.php (published by php artisan pwa:install or php artisan vendor:publish --tag="pwa::config"). Config changes change the service worker version, so devices update themselves after you deploy with pwa:build.

Environment variables ​

VariableKeyDefault
PWA_ENABLEDenabledtrue unless APP_ENV=local
PWA_NAMEnameAPP_NAME
PWA_SHORT_NAMEshort_namenull (= name)
PWA_DESCRIPTIONdescriptionnull
PWA_DISPLAY_STRATEGYdisplay.strategyoverride
PWA_KILL_SWITCH_STOREsw.kill_switch_storenull (default cache store)
PWA_LOG_CHANNELtelemetry.channelnull (default log)
PWA_PUSH_ENABLEDpush.enabledfalse
PWA_VAPID_SUBJECTpush.vapid.subjectAPP_URL
PWA_VAPID_PUBLIC_KEY, PWA_VAPID_PRIVATE_KEYpush.vapid.*null (pwa:push:vapid)

General ​

KeyTypeDefaultDescription
enabledbooltrue outside localEnables the service worker. When false, the client unregisters any existing service worker and /sw.js returns a self-destroying service worker. The manifest and components keep working.
route_prefixstringpwaPrefix for the internal routes (/pwa/session, /pwa/ping, /pwa/client.js, /pwa/telemetry).

Identity ​

KeyTypeDefaultDescription
namestringAPP_NAMEFull name in the install dialog and the app list.
short_name?stringnullShown under the home screen icon; 12 characters or fewer. Falls back to name.
description?stringnullDescription in the install dialog (Chromium).
idstring/The app's identity. Never change it after release: a new id means a new app, and the old one stays installed.
start_urlstring/?source=pwaWhere the app opens. source=pwa marks the session as an installed app (not used for remember-me).
scopestring/Which URLs belong to the app. start_url must be inside it.

You can translate name, short_name and description in lang/vendor/pwa/{locale}/manifest.php (keys name, short_name, description).

Display ​

KeyTypeDefaultDescription
display.strategyoverride, adaptive, fixedoverrideSee Display mode.
display.valuestringstandaloneThe display value (standalone, minimal-ui, fullscreen, browser).
display.overridelist['minimal-ui']display_override for the override strategy.
display.desktopstringminimal-uiThe desktop mode for the adaptive strategy.
orientation?stringnullFor example portrait; usually best left unset (tablets).
desktop_nav.enabledbooltrueRender <x-pwa::nav/>.
desktop_nav.min_widthint900The window width from which the component treats the device as a desktop.

Appearance and icons ​

KeyTypeDefaultDescription
theme.lighthex#0d6efdtheme_color and the light theme-color; accent of the offline and maintenance screens.
theme.darkhex#0b1220theme-color for dark mode.
theme.accent_darkhex#5b9dffAccent of the offline and maintenance screens in dark mode.
theme.backgroundhex#ffffffbackground_color (Android splash screen), background of the maskable and iOS icons.
icons.source?stringnullDefault source image for pwa:icons.
icons.pathstringpwa/iconsIcon folder inside public/.
icons.sizeslist<int>[192, 512]Sizes of icon-{size}.png.
icons.maskable_paddingfloat0.1Padding of the maskable icon (the safe zone is 80%).
icons.splash.background?hexnullBackground of the iOS startup images; null = theme.background.
icons.splash.dark_background?hexnullAdds prefers-color-scheme: dark variants with this background.
icons.splash.icon_sizefloat0.3Icon edge as a fraction of the shorter screen edge.
icons.splash.orientationslist<string>['portrait', 'landscape']Orientations to generate.
icons.splash.devices?list<string>nullKeys of AppleDevices::SCREENS; null = all iPhones and iPads.
screenshotslist[]Screenshots for the richer install dialog (src, sizes, type, form_factor), see Manifest.

OS integration ​

KeyTypeDefaultDescription
categorieslist[]Store and launcher categories, for example ['business'].
shortcutslist[]Icon shortcuts: ['name' => …, 'url' => …, 'icon' => …].
share_target?arraynullThe full share_target object; easier with Pwa::manifest()->shareTarget().
file_handlerslist[]Opening files from the OS (Chromium desktop).
protocol_handlerslist[]Custom web+… schemes.
launch_handlerarrayclient_mode: [navigate-existing, auto]How an app that is already running opens.
scope_extensionslist[]Additional domains of the same app; each needs /.well-known/web-app-origin-association.
localeslist[]Manifest languages, including the default one: *_localized members (Chromium 147+) and a ?lang= link based on the page language.

Service worker ​

KeyTypeDefaultDescription
sw.urlstring/sw.jsThe service worker URL. Never put a file with the same name in public/.
sw.importlist[]Scripts loaded with importScripts before the runtime (push system, Sentry). Their content changes the service worker version.
sw.extendlist[]Scripts loaded after the runtime; they get self.PwaWorker (custom routes and strategies). See Service worker.
sw.vite_manifeststringbuild/manifest.jsonVite manifest in public/ used for precaching.
sw.build_directorystringbuildVite asset prefix (cache-first).
sw.compiled_pathstringbootstrap/cache/pwaWhere pwa:build stores the built service worker.
sw.kill_switch_store?stringnullCache store for pwa:disable; with multiple servers, use a shared one (Redis, database).

Cache ​

KeyTypeDefaultDescription
manifest.resolverslist[]ManifestResolver classes (resolved from the container) for a per-request manifest. See Manifest.
cache.navigation_timeoutint (s)3After how many seconds of a slow network the cached page is used.
cache.ruleslist[]Cache rules (match, destination, strategy, cache, max_entries, max_age, timeout, shared). See Cache rules.
cache.apilist[]Shortcut: GET paths (with *) served network-first, for example ['/api/catalog*'].
cache.images.enabledbooltrueDefault rule for images and fonts (stale-while-revalidate).
cache.images.max_entriesint120Maximum number of cached images and fonts.
cache.images.max_ageint (s)30 daysOlder images are fetched again (offline, an older one is still used).
cache.never_cachelistlogin, logout, register, broadcasting, livewire, sanctum, /pwa/*Paths the service worker never stores or queues; fetch/XHR requests just pass through to the network, and the user identity is read from their responses.

Offline ​

KeyTypeDefaultDescription
offline.enabledbooltrueThe offline screen and its route.
offline.routestring/offlineURL of the offline screen (precached).
offline.precachelist[]Additional URLs to precache, for example ['/manifest.webmanifest', '/img/logo.svg'].
offline.queuebooltrueQueue POST/PUT/PATCH/DELETE requests during a network failure.
offline.warm.urlslist<string>[]Pages downloaded ahead of time; per user with Pwa::warmUsing(), see Warm-up.
offline.warm.maxint20Maximum number of pages per warm-up.
offline.warm.intervalint60Minutes between automatic warm-ups (a sign-in always warms).

Session ​

KeyTypeDefaultDescription
session.standalone_rememberbooltruepwa.remember forces remember-me in the installed app.
session.keepalive_minutesint10Keep-alive interval while the app is visible (0 = only when the user returns).
session.refresh_csrfbooltrueRefresh the CSRF token and retry fetch after a 419.
session.remember_fieldstringrememberName of the remember-me field in the login form.

Maintenance mode ​

KeyTypeDefaultDescription
maintenance.message?stringnullMessage on the maintenance screen (otherwise the translated default text).
maintenance.until?stringnullExpected end (ISO 8601); set by pwa:down --until.
maintenance.retryint (s)60Default Retry-After and check interval (15–300 s).
maintenance.refresh?intnullDefault --refresh for pwa:down.

Install, telemetry, adapters ​

KeyTypeDefaultDescription
install.min_visitsint2The visit from which <x-pwa::install/> is shown.
install.dismiss_daysint30How long to hide the prompt after the user dismisses it.
install.ios_hintbooltrueThe "Share → Add to Home Screen" hint on iPhone and iPad.
telemetry.logbooltrueWrite TelemetryReceived to the log; turn it off when you handle the events yourself (Events).
telemetry.enabledbooltrueSend service worker errors to /pwa/telemetry.
telemetry.channel?stringnullLog channel; a channel that does not exist falls back to the default log.
telemetry.max_eventsint20Maximum number of events per request.
adapters.livewirebooltrueLivewire 3 adapter.
adapters.inertiabooltrueInertia adapter.
adapters.reload_on_resumeboolfalseInertia reload() when the user returns to the app.

Web push ​

See Push notifications.

KeyTypeDefaultDescription
push.enabledboolfalseThe optional push module: subscription routes, Pwa.push, the worker's push listeners.
push.vapid.subjectstringAPP_URLContact for push services: mailto: or https://.
push.vapid.public_key, push.vapid.private_key?stringnullWritten by pwa:push:vapid; new keys invalidate every subscription.
push.modelclass-stringPush\PushSubscriptionYour own model must extend it.
push.tablestringpwa_push_subscriptionsTable of the published migration.
push.middlewarelist['auth']Middleware of the subscription routes (after web, throttled to 20/min).
push.max_subscriptionsint10Devices per owner; the least recently used is removed first.
push.endpoints?listFCM, Mozilla, Windows, ApplePush service hosts the server accepts and sends to (* wildcard); null = any https host.
push.ttlint (s)2419200How long the push service keeps an undelivered message (28 days).
push.urgencystringnormalvery-low, low, normal, high.
push.icon, push.badge?stringnullDefaults for messages; null = icon-192.png and monochrome-512.png from icons.path when they exist.
push.handle_in_workerbooltrueThe worker shows notifications and handles clicks; false when a sw.import script does it.

Released under the MIT License.