Stimulus 3 Support

Stimulus 3.0 – a new major version – was released in September. It includes
a few nice new features – like a „debug“ mode and „values defaults“ – but no
major changes and no backwards compatibility breaks.

So why the new major version? Because the library was renamed from stimulus
to @hotwired/stimulus. Yup, the name of the library changed… but not much
else. However, the name change required Symfony’s UX libraries to need a new
major version.

Symfony UX Changes

There are 4 big changes with the new Symfony UX releases:

1) Support changed from stimulus to @hotwired/stimulus

The biggest change with the new major releases listed above is that support for
stimulus was dropped and replaced with @hotwired/stimulus (i.e. version
3 of the library). This difference won’t be noticeable in your applications,
except that you’ll need to adjust the import { Controller } from ’stimulus‘
lines in your code (see about upgrading below).

2) Support for IE11 was dropped

Version 3 of Stimulus dropped support for IE11. We did the same thing in our
Symfony UX libraries and incorporated a brand new build system. The result is
smaller final JavaScript sizes. If you need to continue supporting IE 11, use
Stimulus 2 and the previous version of the UX libraries.

3) data- Attributes Changed to the Values API

Many of the UX packages allowed you to configure things by adding data- attributes
to an element. Those have been replaced by using the „Values API“ from Stimulus,
which is a bit nicer anyways. For example, if you use symfony/ux-lazy-image,
then previously the code looked like this:

This code would now need to be updated to this:

See the README – or CHANGELOG (e.g. Lazy Image CHANGELOG) – of each library for
a full set of changes.

In addition to the above items, symfony/ux-chartjs was updated to use chart.js
version 3, and various new events were added to UX controllers to make them more
configurable.

How do I Upgrade?

To upgrade, you’ll need to update a number of packages at the same time and make
an adjustment to each Stimulus controller in your project:

Remove stimulus from your package.json file and replace it with
„@hotwired/stimulus“: „^3.0“. Also change your @symfony/webpack-encore
version to ^1.7 and @symfony/stimulus-bridge to ^3.0. After making
these changes, run yarn install.

Update all of your controllers to replace any imports for stimulus with
imports from @hotwired/stimulus:

In composer.json, update any symfony/ux-* packages that you have installed
to version ^2.0. Run composer up „symfony/ux-*“. Once that finishes,
run yarn install –force.

And… that’s it! Congratulations on upgrading to Stimulus 3.

Happy UX’ing!