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:

{# Code for the old, 1.x version #}
<img
    src="{{ asset('image/small.png') }}"
    {{ stimulus_controller('symfony/ux-lazy-image/lazy-image') }}
    data-hd-src="{{ asset('image/large.png') }}"
/>

This code would now need to be updated to this:

{# Code for the new, 2.x version #}
<img
    src="{{ asset('image/small.png') }}"
    {{ stimulus_controller('symfony/ux-lazy-image/lazy-image', {
        src: asset('image/large.png')
    }) }}
/>

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:

1. 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 or later. After making these changes, run yarn install.

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

   -import { Controller } from 'stimulus';
   
   +import { Controller } from '@hotwired/stimulus';

3. 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!