Laravel PWA

To add PWA support to your Laravel application, follow these steps:

1. Initial Installation: Run the artisan command to publish the necessary configuration, manifest, service worker, and assets.
2. Configuration: Modify the config/pwa.php file to set your manifest values.
3. Manifest Update: After changing configuration values, you must run the update command to sync changes to public/manifest.json.

Note: PWA features (service workers and installability) require HTTPS to function correctly.

# Initial package publishing
php artisan erag:install-pwa

# Run this after changing config/pwa.php manifest values
php artisan erag:update-manifest

To enable PWA features like the manifest link and service worker registration, add the following Blade directives to your main layout file:

1. @PwaHead inside the <head> tag.
2. @RegisterServiceWorkerScript inside the <body> tag.

This works for standard Blade, Livewire, and single-page application (SPA) shells like React or Vue.

<!DOCTYPE html>
<html lang="en">
<head>
    @PwaHead
    <title>{{ config('app.name') }}</title>
</head>
<body>
    {{ $slot ?? '' }}

    @RegisterServiceWorkerScript
</body>
</html>

Install the package into your Laravel project using Composer:

composer require erag/laravel-pwa

To enable PWA features in your frontend, add the provided Blade directives to your main layout file:

1. Add Meta Tags: Place @PwaHead inside the <head> tag.
2. Register Service Worker: Place @RegisterServiceWorkerScript just before the closing </body> tag.

<!DOCTYPE html>
<html lang="en">
<head>
    @PwaHead
    <title>Your App Title</title>
</head>
<body>
    <!-- Your content -->

    @RegisterServiceWorkerScript
</body>
</html>

Depending on your Laravel version, you must register the EragLaravelPwaServiceProvider.

For Laravel v11.x, v12.x, and v13.x

Add the provider to your /bootstrap/providers.php file:

use EragLaravelPwa\[EragLaravelPwaServiceProvider::class;

return [
    // ...
    EragLaravelPwaServiceProvider::class,
];

For Laravel v8.x, v9.x, and v10.x

Add the provider to the providers array in config/app.php:

'providers' => [
    // ...
    EragLaravelPwa\EragLaravelPwaServiceProvider::class,
],

use EragLaravelPwa\EragLaravelPwaServiceProvider;

return [
    // ...
    EragLaravelPwaServiceProvider::class,
];

After registering the service provider, run the following Artisan command to publish the configuration files and set up the PWA functionality:

php artisan erag:install-pwa

This creates config/pwa.php.

To install the package, require it via Composer and then run the installation command to publish the necessary configuration and public assets.

composer require erag/laravel-pwa
php artisan erag:install-pwa

To enable PWA functionality in your Laravel Blade templates, you must include two specific directives in your main layout file:

1. Metadata: Place @PwaHead inside the <head> section to inject PWA-related meta tags and links.
2. Service Worker: Place @RegisterServiceWorkerScript before the closing </body> tag to register the service worker script.

These directives ensure the browser receives the correct manifest links and service worker registration logic.

<!-- Example Layout -->
<html>
<head>
    <!-- ... other tags ... -->
    @PwaHead
</head>
<body>
    <!-- ... content ... -->

    @RegisterServiceWorkerScript
</body>
</html>

The PWA configuration is managed in config/pwa.php. Key options include:

• install-button: Boolean to enable/disable the install button.
• manifest: An array containing name, short_name, background_color, display, description, theme_color, and icons.
• livewire-app: Set to true if using Livewire.

Important: After modifying config/pwa.php, you must run the manifest update command to regenerate the public/manifest.json file.

php artisan erag:update-manifest

The package provides a built-in UI for prompting users to install the app. To enable this, set the following configuration key to true:

config('pwa.install-button') = true

When enabled, RegisterServiceWorkerScript() will inject:

1. HTML: A floating action button (#install-button) and an instruction tip for iOS users (.ios-tip).
2. CSS: Styles for a pulsing animation on the install icon.
3. JavaScript: Logic to handle the beforeinstallprompt event (for Android/Chrome) and specific instructions for Safari on iOS (where users must manually use the 'Add to Home Screen' feature).

You can publish the package's configuration and essential PWA assets (manifest, offline page, service worker, and logo) to your application's public and config directories using the following Artisan commands. This allows you to customize the manifest, logo, and offline experience.

# Publish the main configuration file
php artisan vendor:publish --tag=erag:publish-pwa-config

# Publish the manifest.json file
php artisan vendor:publish --tag=erag:publish-manifest

# Publish the offline.html page
php artisan vendor:publish --tag=erag:publish-offline

# Publish the service worker (sw.js)
php artisan vendor:publish --tag=erag:publish-sw

# Publish the default logo (logo.png)
php artisan vendor:publish --tag=erag:publish-logo