Symfony UX is an initiative and set of libraries centered around the
Stimulus JavaScript library. And today, I'm pleased to announce several
new releases:

• Version 2.0 of all symfony/ux libraries
• Version 3.0 of @symfony/stimulus-bridge
• Version 2.0 of @symfony/stimulus-testing

What does this all mean? Let's find out!

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 and @symfony/stimulus-bridge to ^3.0. 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!

Sponsor the Symfony project.