Symfony UX 2.0 & Stimulus 3 Support

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 #}

This code would now need to be updated to this:

    {# Code for the new, 2.x version #}

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:

    -import { Controller } from 'stimulus';

+import { Controller } 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!

                Sponsor the Symfony project.

https://symfony.com/blog/symfony-ux-2-0-and-stimulus-3-support?utm_source=Symfony%20Blog%20Feed&utm_medium=feed