PHPackages                             heimrichhannot/contao-pwa-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. heimrichhannot/contao-pwa-bundle

ActiveContao-bundle[Utility & Helpers](/categories/utility)

heimrichhannot/contao-pwa-bundle
================================

A bundle to provide progressive web app support for contao.

0.9.1(2mo ago)61.0k3[2 issues](https://github.com/heimrichhannot/contao-pwa-bundle/issues)LGPL-3.0-or-laterPHPPHP ^8.2CI failing

Since Jan 8Pushed 2mo ago4 watchersCompare

[ Source](https://github.com/heimrichhannot/contao-pwa-bundle)[ Packagist](https://packagist.org/packages/heimrichhannot/contao-pwa-bundle)[ RSS](/packages/heimrichhannot-contao-pwa-bundle/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (25)Versions (52)Used By (0)

Contao Progressive Web App Bundle
=================================

[](#contao-progressive-web-app-bundle)

A comprehensive bundle that provides Progressive Web App (PWA) support for Contao CMS, enabling modern web application features for your Contao websites.

Features
--------

[](#features)

- Create and register manifest files for each page root
- Generate and register service workers for each page root
- Send custom push notifications from the backend
- Set an offline fallback page for improved user experience
- content elements to manage push notification subscriptions

Installation
------------

[](#installation)

### Install with Composer

[](#install-with-composer)

```
composer require heimrichhannot/contao-pwa-bundle
```

After installation, update your database.

### Requirements

[](#requirements)

- PHP ^8.2
- Contao ^5.3

### Additional Dependency for Push-Notifications

[](#additional-dependency-for-push-notifications)

To enable web push notifications, you'll need to install [web-push-libs/web-push-php](https://github.com/web-push-libs/web-push-php) (versions 5 to 10 are supported):

```
composer require minishlink/web-push:^8.0

```

Additionally, ensure the following PHP extensions are installed and enabled:

- gmp
- mbstring
- curl
- openssl

Setup
-----

[](#setup)

1. If you want to use push notifications, add VAPID keys to your configuration (see [VAPID Keys](#vapid-keys) section below).
2. Create a PWA Configuration in the Contao backend (System → PWA Configuration).
3. Add the configuration to a page root:
    - Navigate to page settings
    - Find the "Progressive Web App" section
    - Select "Yes" and choose your configuration
    - Upon saving, the page manifest and service worker will be generated automatically
4. To provide an option for users to register for push notifications, add either:
    - The push subscription button content element, or
    - The push notification popup element to your page

### VAPID Keys

[](#vapid-keys)

For push notifications, you need to add your server VAPID keys to your config file, typically in your project's `config.yml`. If you don't have VAPID keys yet, you can generate them in the PWA Bundle backend (Contao Backend → System → PWA Configuration → Control → Authentication).

```
huh_pwa:
    vapid:
        subject: "mailto:your-email@example.org"
        publicKey: "YOUR_PUBLIC_KEY"
        privateKey: "YOUR_PRIVATE_KEY"
```

Usage
-----

[](#usage)

### Content Elements

[](#content-elements)

This bundle provide 4 content elements:

- Install Pwa Button: A simple button that can be used to trigger the "Add to homescreen" prompt
- Offline Pages: Show cached offline pages (can be used to show the user all working link on the offline page)
- Push Subscription: Display a button to subscribe/unsubscribe to push notifications
- Push Notification Popup: See description below

#### Push Notification Popup

[](#push-notification-popup)

This content element can be used to show a popup to the user, asking them to subscribe to push notifications. By default, the popup opens on button click, but you can also set it to open automatically when the page loads. A template for bootstrap 5 modals is included. The templates are prepared to easily create variant of them without overriding greater parts of the template.

### Regenerating Files

[](#regenerating-files)

You can regenerate all manifest and service worker files at once from:

- The PWA Control panel (Contao Backend → System → PWA Configuration → Control → Files → Rebuild files)
- Or by using the command: `huh:pwa:build`

Development
-----------

[](#development)

### JavaScript Events

[](#javascript-events)

To support custom controls, the bundle provides events and event listeners that can be used. All events are dispatched and listened to on the `document` object.

#### Events

[](#events)

EventDescriptionhuh\_pwa\_sw\_not\_supportedFired if the browser doesn't support service workers or no service worker is foundhuh\_pwa\_push\_not\_supportedFired if the browser doesn't support push notificationshuh\_pwa\_push\_permission\_deniedFired if push notifications are blocked in the browserhuh\_pwa\_push\_isSubscribedFired when subscribed to push notifications (on page load or when subscribing)huh\_pwa\_push\_isUnsubscribedFired when unsubscribed from push notifications (on page load or when unsubscribing)huh\_pwa\_push\_subscription\_failedFired when subscription to push notifications fails. Error reason can be found in event.detail.reasonhuh\_pwa\_push\_unsubscription\_failedFired when unsubscribing from push notifications fails. Error reason can be found in event.detail.reason#### Listeners

[](#listeners)

Event typeUsageDescriptionhuh\_pwa\_push\_changeSubscriptionState`new CustomEvent('huh_pwa_push_changeSubscriptionState', {detail: ['subscribe' | 'unsubscribe']})`Fire this event when the user interacts with your control to change their subscription state. Use a `CustomEvent` with detail parameter set to subscribe or unsubscribe### Complete Configuration

[](#complete-configuration)

```
huh_pwa:
    vapid:
        subject: "mailto:your-email@example.org"
        publicKey: "YOUR_PUBLIC_KEY"
        privateKey: "YOUR_PRIVATE_KEY"
    push:
        automatic_padding: 2847 # int (payload size in byte (min 0, max 4078)) or boolean (enable/disable)
    manifest_path: '/pwa' # where the manifest files should be located within web folder
    configfile_path: '/pwa' # where the configuration files should be located within web folder
```

### Commands

[](#commands)

CommandDescriptionhuh:pwa:build(Re)Build config-specific files like service worker and manifesthuh:pwa:send-pushSend unsent push notificationsTodo
----

[](#todo)

- Image size configuration
- Support for SVG icons
- Selective page precaching
- Customizable "Add to homescreen" and push notification prompts

###  Health Score

53

—

FairBetter than 97% of packages

Maintenance80

Actively maintained with recent releases

Popularity25

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor1

Top contributor holds 95.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~56 days

Recently: every ~198 days

Total

47

Last Release

66d ago

PHP version history (4 changes)0.1.0PHP ^7.1

0.8.11PHP ^7.1||^8.0

0.8.13PHP ^7.4 || ^8.0

0.9.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/28ad3224d8727b622ebd229840eea6b9dbcb83eb0bd609e6ce65b614830ff538?d=identicon)[digitales@heimrich-hannot.de](/maintainers/digitales@heimrich-hannot.de)

---

Top Contributors

[![koertho](https://avatars.githubusercontent.com/u/12064642?v=4)](https://github.com/koertho "koertho (137 commits)")[![LongDuc89](https://avatars.githubusercontent.com/u/183475641?v=4)](https://github.com/LongDuc89 "LongDuc89 (3 commits)")[![ericges](https://avatars.githubusercontent.com/u/25957923?v=4)](https://github.com/ericges "ericges (1 commits)")[![matuweb](https://avatars.githubusercontent.com/u/13745042?v=4)](https://github.com/matuweb "matuweb (1 commits)")[![mktcode](https://avatars.githubusercontent.com/u/6792578?v=4)](https://github.com/mktcode "mktcode (1 commits)")

###  Code Quality

Static AnalysisPHPStan, Rector

Code StyleECS

Type Coverage Yes

### Embed Badge

![Health badge](/badges/heimrichhannot-contao-pwa-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/heimrichhannot-contao-pwa-bundle/health.svg)](https://phpackages.com/packages/heimrichhannot-contao-pwa-bundle)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M650](/packages/sylius-sylius)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[contao/core-bundle

Contao Open Source CMS

1231.6M2.3k](/packages/contao-core-bundle)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)[codefog/contao-haste

haste extension for Contao Open Source CMS

42650.8k139](/packages/codefog-contao-haste)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)