# Progressive Web App (PWA)
The Boilerplate package provides built-in support for Progressive Web App (PWA) functionality, allowing you to transform your admin panel into an installable web application.
# Configuration
PWA support is controlled through the app.php
configuration file. Add or modify the pwa
section:
// Progressive Web App configuration
'pwa' => [
'enabled' => false,
'name' => 'Admin Panel',
'short_name' => 'Admin',
'description' => 'Administration Panel',
'theme_color' => '#007bff',
'background_color' => '#ffffff',
'display' => 'standalone',
'orientation' => 'portrait',
'icons' => [
[
'src' => 'favicon.svg',
'sizes' => 'any',
'type' => 'image/svg+xml'
],
[
'src' => 'icon-192.png',
'sizes' => '192x192',
'type' => 'image/png'
],
[
'src' => 'icon-512.png',
'sizes' => '512x512',
'type' => 'image/png'
]
]
]
# Configuration Options
enabled
: Enable or disable PWA functionalityname
: Full application name displayed during installationshort_name
: Short name displayed on the home screendescription
: Application descriptiontheme_color
: Browser UI color (address bar, etc.)background_color
: Splash screen background colordisplay
: Display mode (standalone
,minimal-ui
,fullscreen
,browser
)orientation
: Screen orientation (portrait
,landscape
,any
)icons
: Array of icon definitions withsrc
,sizes
, andtype
# Activation
To enable PWA functionality:
- Set
enabled
totrue
in your configuration - Ensure you have the required icon files in your
public
directory - The manifest route will be automatically registered at
/manifest.json
# Manifest Generation
When PWA is enabled, the package automatically:
- Registers a route at
manifest.json
- Generates the manifest dynamically based on your configuration
- Adjusts
start_url
andscope
based on your app's prefix and domain settings - Converts icon paths to full URLs using Laravel's
asset()
helper
The manifest route name is boilerplate.pwa.manifest
.
# Required Assets
Ensure you have the following icon files in your public
directory:
favicon.svg
- Scalable vector icon (recommended)icon-192.png
- 192×192 pixel PNG icon (required for installation)icon-512.png
- 512×512 pixel PNG icon (required for installation)
You can customize the icon configuration in the pwa.icons
array to include additional sizes or different file formats.
# URL Handling
The package automatically handles URL configuration:
- Start URL: Uses the configured app prefix (e.g.,
/admin
if prefix is set toadmin
) - Scope: Automatically sets scope to include the app prefix with trailing slash
- Domain: Respects the configured domain setting for absolute URLs
# Installation
Once configured and enabled:
- Modern browsers will detect PWA capability
- Users will see an installation prompt when criteria are met
- The app can be installed to the device's home screen
- It will launch in standalone mode without browser UI
# Browser Requirements
PWA features require:
- Valid manifest.json file
- HTTPS connection (or localhost for development)
- At least one valid icon (192x192 minimum)
- Modern browser support (Chrome 57+, Firefox 58+, Safari 11.1+, Edge 17+)
# Troubleshooting
Manifest not loading: Verify PWA is enabled in configuration and check the route is registered.
Installation prompt not showing: Ensure all PWA criteria are met (HTTPS, valid manifest, required icons).
Icons not displaying: Check file paths exist in public directory and match configuration.
Wrong URLs in manifest: Verify your app's prefix and domain configuration settings.