Symfony 6 Certification New exam with updated questions 100% online Show your expertise

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:

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:

1
2
3
4
5
6
{# 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:

1
2
3
4
5
6
7
{# 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:

    1
    2
    3
    -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!

Help the Symfony project!

As with any Open-Source project, contributing code or documentation is the most common way to help, but we also have a wide range of sponsoring opportunities.

Comments

Thank you for your work! Awesome!
Very nice!
Thx Ryan, upgrade done!
> 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.

stimulus-use (stable version) is still incompatible with stimulus 3. And also they claim

> ⚠️ Stimulus 3 has several breaking changes.

Symfonycasts still promote stimulus-use https://symfonycasts.com/screencast/stimulus/stimulus-use (and it's actually pretty handy lib) although this tutorial is non-reproducible (unless you switch to beta, which is probably ok for tutorial or pet project, but no further)

After 2 months it's still "hanging" and I'm not comfortable with using beta versions in prod (branch and PR are there, but failing tests in CI are scary)

Altogether that conveys an image and "feeling" of immature/unstable ecosystem at best

* symfony-ux and encore pushes to stimulus v3 (see symfony/webpack-encore-bundle recipe)
* symfony/ux components use stimulus v3
* symfonycasts promotes to use of stimulus-use (great library all around)

but they are incompatible. For new projects that creates friction in sense that "old stimulus mindset and skills" are of limited use. For old projects that's basically a blocker for updating symfony/webpack-encore-bundle recipe (and moving to stimulus v3), but symfony/ux-* dependes on stimulus 3 now in symfony 6
Login with SymfonyConnect to post a comment