README

Turn your Laravel application into a Progressive Web App (PWA) with push notifications and more.

Dependencies

Installation

Install the package via Composer:

composer require jonnx/laravel-pwa

Add Push Subscription Trait to User Model

use NotificationChannels\WebPush\HasPushSubscriptions;
...
class User extends Authenticatable
{
    use HasPushSubscriptions

Publish the config and components:

php artisan vendor:publish --force --tag=laravel-pwa-config
php artisan vendor:publish --force --tag=laravel-pwa-components
php artisan webpush:vapid
php artisan migrate

Usage

Add the PWA head and scripts to your layout:

@laravelPwaHead
@laravelPwaScripts

PWA Install Banners

This package provides two install banners to help users install your PWA:

<x-pwa.install-banner /> — Displays a banner and prompts the user to install the app using the browser's native install prompt (supported in Chrome, Edge, and most Android browsers). The banner only appears if the app is not already installed and the browser supports the install prompt.
<x-pwa.install-banner-manual /> — Displays a banner with manual installation instructions for browsers that do not support the native install prompt (such as Safari on iOS and macOS). The banner automatically detects the user's platform and provides tailored instructions (e.g., "Add to Home Screen" for iOS, "Add to Dock" for macOS Safari).

Include these components in your layout to provide a seamless install experience for all users:

<x-pwa.install-banner />
<x-pwa.install-banner-manual />

Push Notification Setup

Vapid Keys

To enable push notifications, you need to generate VAPID API keys:

php artisan webpush:vapid

This will generate the required keys and update your .env and config/pwa.php files. Make sure to configure your environment and PWA settings accordingly.

User Model Push Subscription Trait

This trait automatically establishes the relationship from the user model to many push subscriptions. This way a user can opt-in to push notifications on multiple devices and receive notifications everywhere.

use NotificationChannels\WebPush\HasPushSubscriptions;
...
class User extends Authenticatable
{
    use HasPushSubscriptions

Web Push Subscription Handler

Use the push notification subscription handler Livewire component. This captures the subscription data and automatically saves it to the user on the back-end so that you can use the subscription to send notifications anytime.

@livewire('push-notification-subscription-handler')

User Permission Banner

Push notifications require active user opt-in on all browsers. Include this components in your layout to provide a seamless opt-in experience.

<x-pwa.push-notification-banner />

Testing Push Notifications

To simplify testing and debugging during setup, this package provides a component to test push notifications with. Include this component in any of your pages and click the button. A test push notification should appear on each of your user's subscribed devices.

Here is how it works:

The component renders a simple button.
When clicked, it triggers the sendTestNotification method in its Livewire class.
The method sends a test push notification to all devices currently subscribed for the authenticated user.
This allows you to verify that push notification setup, browser permissions, and subscription storage are working correctly.

@livewire('push-notification-test-button')

Creating Your Own Push Notifications

Simple

This package provides a helper class you can use to create your own notifications quickly. the service worker is already setup to open the url on the user's device when they click the notification.

$user->notify(new Notification(
    title: 'Test Push Notification',
    body: 'This is a test push notification from Laravel PWA package. Clicking it will take you to the settings page.',
    openUrl: url('/settings')
));

Advanced

The class we provide is just a simplified wrapper around DeclarativeWebPushMessage. To learn more about this, checkout the documentation here: https://github.com/laravel-notification-channels/webpush?tab=readme-ov-file#declarative-web-push-messages

Customizing Banner Components

The setup steps publish the banner components to a folder in your project so you can easily tweak appearance, position and more. The files are located in the resources/views/pwa folder.

Major Library Dependencies

Library	Purpose
laravel/webpush	Handles browser push notifications, VAPID key management, and subscription storage.
livewire/livewire	Enables reactive components for subscription handling and real-time UI updates.
alpinejs	Provides lightweight frontend interactivity for banners and install prompts.
notification-channels/webpush	Adds push notification support to Laravel's notification system.

These libraries are required to:

Manage push notification subscriptions and permissions.
Provide real-time, interactive UI components for banners and prompts.
Integrate with browser APIs for PWA installation and notifications.

For more details, see the package documentation or open an issue if you need help.

Contributing

Contributions are welcome! To contribute to this package:

Fork the repository and create your branch from main.
Make your changes, following PSR standards and best practices.
Add or update tests as needed.
Submit a pull request with a clear description of your changes.

If you have ideas, feature requests, or find bugs, please open an issue.

jonnx / laravel-pwa

Maintainers

Details