Symfony News

Webpack Encore 1.0 & Stimulus Bridge 2.0 Released!

We’ve been busy with the Symfony UX Initiative. Today I’m excited to share the next round of updates.

Encore 1.0 Released (Webpack 5 Support)

Contributed by
Vincent Le Biannic
in #645.

After 4 years (of already being stable), we’re proud to welcome Webpack Encore 1.0 to the family. What’s new? Excellent question!

  • Encore now uses Webpack 5, which itself introduces a lot of features.
  • Persistent build cache: thanks to a new Encore.enableBuildCache() method, you can enjoy faster “subsequent” builds. See Encore’s index.js file for more details.

To upgrade, run:

$ yarn upgrade "@symfony/webpack-encore@^1.0.0"

When you next execute Encore, it will probably notify you of other dependencies that you should upgrade. See the full 1.0.0 CHANGELOG.

symfony/stimulus-bridge 2.0

At the heart of the Symfony UX Initiative is Stimulus and the stimulus-bridge, which helps you automatically load controllers from the UX Packages as well as your own custom controllers. 2.0 brings a few awesome updates.

If you want to go deeper, we’ll talk about Stimulus in detail in a Stimulus Tutorial on SymfonyCasts soon.

Lazy Controllers

Contributed by
Ryan Weaver
in #15.

First, in controllers.json, the webpackMode key has been replaced by fetch. This enables a powerful new feature: if you set fetch to lazy for a package, that package’s JavaScript won’t be downloaded until it’s needed! How is that possible? Internally (by leveraging Stimulus & Webpack), the controller code is split into its own JavaScript file. Then, the moment a matching data-controller= appears on the page, the file will be downloaded and executed.

A great use-case is ux-chartjs. By setting fetch: 'lazy', you can build a Chart in PHP and render it on any page… but without incurring any extra code in the JavaScript that’s downloaded on page load.

Laziness for Your Controllers

This “lazy controllers” feature is so neat that we wanted to allow you to use it for your own controllers. By default, if you put a controller file in assets/controllers, it will be automatically loaded but included on every page. What if you only need that controller in rare situations?

You can now tell the stimulus-loader to load your controller “lazy” by decorating it with a special comment:

// assets/controllers/hello_controller.js
import { Controller } from 'stimulus';

/* stimulusFetch: 'lazy' */
export default class extends Controller {
    // ...

By including the /* stimulusFetch: 'lazy' */ comment, this entire controller file (and its dependencies) won’t be downloaded until a matching data-controller element appears on the page.

Upgrading to stimulus-bridge 2.0

To upgrade, make sure you have 2.0 of the package and at least 1.0 of Encore:

$ yarn upgrade "@symfony/stimulus-bridge@^2.0.0"
$ yarn upgrade "@symfony/webpack-encore@^1.0.0"

Also make sure you have the latest symfony/flex so it sets the new fetch option in controllers.json:

$ composer up symfony/flex

Finally, in assets/bootstrap.js, make the following changes:

import { startStimulusApp } from '@symfony/stimulus-bridge';
- import '@symfony/autoimport';

- export const app = startStimulusApp(require.context('./controllers', true, /\.(j|t)sx?$/));
+ export const app = startStimulusApp(require.context(
+     '@symfony/stimulus-bridge/lazy-controller-loader!./controllers',
+     true,
+     /\.(j|t)sx?$/
+ ));


Version 2 also changed the format of the third party controller names. For example, the ux-chartjs controller was previously @symfony/ux-chartjs/chart and is now called symfony--ux-chartjs--chart. If you’re using any UX library version 1.2 or higher (e.g. symfony/ux-chart-js), make sure to upgrade to the latest version of stimulus-bridge.

That’s it! Keep watching the blog and Symfony UX for more updates!

Sponsor the Symfony project.

About us

What a Symfony developer should know about the framework: News, Jobs, Tweets, Events, Videos,...

Find us on Twitter

Find us on Facebook