Skip to content

Deprecate the Stimulus controllers shipped by the bundle - #456

Open
Spomky wants to merge 1 commit into
1.6.xfrom
feature/deprecate-stimulus-controllers
Open

Deprecate the Stimulus controllers shipped by the bundle#456
Spomky wants to merge 1 commit into
1.6.xfrom
feature/deprecate-stimulus-controllers

Conversation

@Spomky

@Spomky Spomky commented Aug 14, 2026

Copy link
Copy Markdown
Member

Second step of the scope reduction announced in #372, independent from #455 which covers the service worker helpers. Nothing is removed here: the 27 controllers keep working exactly as before, they just say out loud that they are going away in 2.0.0.

Where the notice sits

In the AbstractController constructor, not in connect().

Fifteen of the twenty-seven controllers override connect() without calling super.connect(), so a base-class hook there would silently never fire for them. No controller defines a constructor, and a derived class has no choice but to call super(), so the constructor is the only airtight seam.

NetworkInformationController is the one controller extending Stimulus' Controller directly rather than AbstractController, so it carries the notice itself.

The warning is reported once per controller identifier: a page mounting the same controller on twenty elements should not print the same line twenty times.

[pwa-bundle] The "pwa--web-push" Stimulus controller is deprecated since 1.6.0 and will be
removed in 2.0.0. Copy the controller into your own application and register it there.
See https://github.com/Spomky-Labs/pwa-bundle/issues/372#issuecomment-5295710299

Page-side helpers

onPeriodicSync() and registerPeriodicSync(), exported through the @spomky-labs/pwa/helpers importmap entry, warn too. Their service worker counterpart (registerPeriodicSyncTask, notifyPeriodicSyncClients) is deprecated in #455, so both halves of that protocol leave together.

Package metadata

The npm README gets a deprecation banner and the package description is prefixed. The registry-level npm deprecate @spomky-labs/pwa-bundle@"*" is a separate manual step, worth doing since only 1.4.0-alpha1 was ever published.

What users should do

Copy the controllers you use into your own application and register them there. They are plain Stimulus controllers with no dependency on the bundle, so nothing is lost in the move, and you get to drop the parts you never needed.

Checks

  • Behaviour verified against a Stimulus stub: a subclass overriding connect() without calling super still warns; the same identifier twice produces a single warning; the standalone controller and the helper both warn. 6 instantiations, 4 unique warnings.
  • node --check on every modified file, package.json still parses
  • PHP suite unaffected, 123 tests green

@Spomky Spomky self-assigned this Aug 14, 2026
@Spomky Spomky added this to the 1.6.0 milestone Aug 14, 2026
@Spomky
Spomky force-pushed the feature/deprecate-stimulus-controllers branch 3 times, most recently from a5f64a3 to 1c56793 Compare August 16, 2026 20:42
The 27 controllers are leaving in 2.0.0. Wrapping a browser API in a generic,
configurable Stimulus controller turns out to be a lot of abstraction for very
little reuse: every project wants its own behaviour, its own UI and its own
error handling. Several of them also push real-time, client-side interactions
through the server and back, a round trip nobody really asks for. The full
rationale is in #372.

The notice sits in the AbstractController constructor rather than in connect():
fifteen controllers override connect() without calling super, so the warning
would never fire for them, whereas a derived class has no choice but to call
super() in a constructor. NetworkInformationController extends Stimulus'
Controller directly and carries the notice itself.

Reported once per controller identifier: a page mounting the same controller on
twenty elements should not print the same line twenty times.

The two page-side helpers exported by the package, onPeriodicSync() and
registerPeriodicSync(), warn as well. Their service worker counterpart is
deprecated in the same release.
@Spomky
Spomky force-pushed the feature/deprecate-stimulus-controllers branch from 1c56793 to 113e0bc Compare August 17, 2026 06:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant