Deprecate the service worker helpers the application can write itself

[Spomky]

First step of the scope reduction announced in #372: the bundle keeps the manifest, the service worker, the favicons and the icons, and stops growing its client-side surface.

Nothing is removed here. Everything stays emitted by default and only becomes opt-out, so upgrading to 1.6.0 changes no behaviour.

The line

Most helpers emitted by WorkboxHelpers wrap service worker events the bundle itself never populates: push, notificationclick, message, periodicsync and the three backgroundfetch events have no producer on the PHP side. Service worker listeners are additive, and the application source configured through serviceworker.src is appended last by the compiler, so a plain self.addEventListener() there does the same job without the indirection.

A helper stays in WorkboxHelpers only when it:

• arbitrates an order between several rules generated by the bundle: registerInstallTask (ClearCache at 0, SkipWaiting at 5, OfflineFallback at 10, cache strategies at 100) and precacheResources;
• carries a state shared between them: registerCacheName / openCache, whose usedCacheNames set is read back by ClearCache;
• or is a plugin factory called by WorkboxPlugin\*: statusGuard, createBackgroundSyncPlugin, createBackgroundSyncPluginWithBroadcast.

Everything else moves to the new WorkboxDeprecatedHelpers: registerCacheFirst (which had no caller at all), registerMessageTask, registerPushTask, registerNotificationAction, registerPeriodicSyncTask, registerBackgroundFetchTask and the background fetch storage. The emitted JavaScript is byte-identical to what it was, plus the deprecation warnings.

The SKIP_WAITING handler stays: it is the service worker half of the contract with the workbox-window registration injected by PwaRuntime, where the page calls wb.messageSkipWaiting(). It is now a plain listener instead of a registerMessageTask call.

Isolating them in one class makes 2.0.0 a git rm.

Reporting the deprecation

Twice, on purpose, because the two signals reach different people.

trigger_deprecation() fires from the extension when keep_deprecated_helpers is left to true, which reaches the applications that configure nothing. And each deprecated function warns from its own body through reportDeprecatedHelper(), once per name, so an application that already stopped calling them gets a silent service worker.

The option itself is deliberately not marked with setDeprecated(): a deprecated node only fires when it is explicitly written out, which would have warned exactly those who already migrated and stayed silent for everyone else.

Background fetch

background_fetch is deprecated too. It decides for the application that a click opens a given URL, that downloads are chunked into a fixed IndexedDB schema and that the notification title is rewritten with {title} ✅. BackgroundFetchCache calls registerBackgroundFetchTask(), so setting keep_deprecated_helpers to false while background fetch is enabled now fails at container build time with an explicit message, rather than with a bare ReferenceError in the browser.

The duplicated db_name node, declared twice in the definition, is removed.

idb

openBackgroundFetchDatabase() was the only consumer of self.idb. Once the deprecated helpers are switched off, the library is no longer imported by WorkboxImport (CDN and local paths) nor copied to the public folder by ServiceWorkerCompiler.

⚠️ This is a behaviour change for an application that uses self.idb in its own serviceworker.src: it must switch to indexedDB.open() or import the library itself. To be covered in the upgrade guide.

Migration

pwa:
    serviceworker:
        workbox:
            keep_deprecated_helpers: false

Before flipping it, replace the calls in your own service worker source:

// registerPushTask(structuredPushNotificationSupport);
self.addEventListener('push', (event) => {
  const { title, options } = JSON.parse(event.data.text());
  event.waitUntil(self.registration.showNotification(title, options));
});

// registerNotificationAction('*', handler);
self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  event.waitUntil(handler(event));
});

// registerPeriodicSyncTask('my-tag', callback);
self.addEventListener('periodicsync', (event) => {
  if (event.tag === 'my-tag') {
    event.waitUntil(callback(event));
  }
});

Checks

• 163 tests, 38 added across WorkboxHelpersTest, WorkboxDeprecatedHelpersTest and WorkboxImportTest
• ECS, Deptrac and PHPStan clean, no new error
• Emitted JavaScript validated with node --check in both configurations

Still to come

The console.warn in the Stimulus controllers, the npm deprecate on @spomky-labs/pwa-bundle, the documentation and the upgrade guide.