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:

1
2
3
4
5
6
7

// 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:

1
2

$ 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:

1

$ composer up symfony/flex

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

1
2
3
4
5
6
7
8
9

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?$/
+ ));

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