Chapters

23 Chapters | 2:07:02 |

01

A World without Build Systems?

4:04
02

Doing Modern JS Right in your Browser

7:41
03

Installing AssetMapper

3:03
04

Mapping Assets

6:01
05

CSS & Background Images

3:26
06

3rd Party CSS

6:09
07

Adding Fonts

3:02
08

Tailwind CSS

5:47
09

JavaScript & importmap

7:38
10

importmap:require - 3rd Party JS Libs

5:07
11

Importing Specific Package Files

4:54
12

Adding Stimulus

8:04
13

Symfony UX Stimulus Packages

4:00
14

Lazy Stimulus Controllers

2:28
15

Debugging

5:12
16

Page-Specific CSS & JS

5:05
17

Excluding Files

3:53
18

Deploying to Platform.sh

6:29
19

Configuring the Platform.sh Deploy

9:08
20

Deploying the Assets

5:04
21

Long-Term Caching, Compression & File Combining

5:27
22

Optimizing & Profiling

6:06
23

Preloading

9:14

> Symfony 6 > AssetMapper: Modern JS with Zero Build System

Buy Access to Course

12.

Adding Stimulus

Autoplay

Keep on Learning!

If you liked what you've learned so far, dive in! Subscribe to get
access to this tutorial plus video, code and script downloads.

Start your All-Access Pass

Buy just this tutorial for $12.00

Previous Challenge

Next Chapter

With a Subscription, click any sentence in the script to jump to that part of the video!

We can write modern JavaScript in this file, we can import third-party packages: we're free to dream up whatever code we want. But, if you're like me, you probably want to use Stimulus. So let's get that installed.

Stimulus is just a JavaScript library, so we could say

php bin/console importmap:require '@hotwired/stimulus'

Then follow their docs on how to get things set up.

Installing StimulusBundle

But Symfony has special integration with Stimulus. So instead, run:

composer require symfony/stimulus-bundle

StimulusBundle is a relatively new package that houses some Twig shortcuts that we'll use, like stimulus_controller(). But, more deliciously, it has a recipe that will set our app up to load Stimulus controllers effortlessly.

Check it out: thanks to the recipe, we now have an assets/controllers/ directory with hello_controller.js inside.

            Copy Code

                            Show All Lines

                        17 lines
            |
            assets/controllers/hello_controller.js
        
            import { Controller } from '@hotwired/stimulus';
        
                Show Lines

                                                    // ... lines 2 - 11
                            
            export default class extends Controller {
        
                connect() {
        
                    this.element.textContent = 'Hello Stimulus! Edit me in assets/controllers/hello_controller.js';
        
                }
        
            }

Without touching anything else, open up templates/vinyl/homepage.html.twig and, right after the <h1>, add a new <div>. Let's attach the new hello controller to this element. Do that with: stimulus_controller() - that's one of the new functions that comes from StimulusBundle - passing hello.

            Copy Code

                            Show All Lines

                        36 lines
            |
            templates/vinyl/homepage.html.twig
        
                Show Lines

                                                    // ... lines 1 - 4
                            
            {% block body %}
        
            <div class="px-4">
        
                Show Lines

                                                    // ... line 7
                            
                <div {{ stimulus_controller('hello') }}></div>
        
                Show Lines

                                                    // ... lines 9 - 33
                            
            </div>
        
            {% endblock %}

That can't possibly work already... right? Refresh. It does. That's bananas! And down in the console, we see logs about Stimulus initializing and our hello controller connecting. With just one composer require line, Stimulus is alive!

How Stimulus Loads

Let's put on our detective hats and delve a bit deeper into how this works and what the recipe actually did. In templates/base.html.twig, this is probably the least important change: it added ux_controller_link_tags(). We'll talk about that in the next chapter when we explore UX packages. But, in short, if a UX package come with their own CSS, this outputs that. Right now, it's not doing anything.

            Copy Code

                            Show All Lines

                        72 lines
            |
            templates/base.html.twig
        
                Show Lines

                                                    // ... lines 1 - 2
                            
                <head>
        
                Show Lines

                                                    // ... lines 4 - 11
                            
                    {% block stylesheets %}
        
                        {{ ux_controller_link_tags() }}
        
                Show Lines

                                                    // ... lines 14 - 15
                            
                    {% endblock %}
        
                Show Lines

                                                    // ... lines 17 - 21
                            
                </head>
        
                Show Lines

                                                    // ... lines 23 - 72

More importantly, the recipe added a new assets/bootstrap.js file. And, in assets/app.js, it sprinkled in some code to import that file. So, app.js loads, that imports bootstrap.js, and then that imports @symfony/stimulus-bundle.

            Copy Code

                            Show All Lines

                        6 lines
            |
            assets/bootstrap.js
        
            import { startStimulusApp } from '@symfony/stimulus-bundle';
        
            const app = startStimulusApp();
        
                Show Lines

                                                    // ... lines 4 - 6

Ooh, that's a bare import! It doesn't start with "../" or "./"! That means our browser will look for it in the importmap to figure out which file to load.

Ok! Go open importmap.php. Surprise! The recipe added two new entries: One for the @hotwired/stimulus library itself and another for @symfony/stimulus-bundle, which points to this weird looking path.

            Copy Code

                            Show All Lines

                        31 lines
            |
            importmap.php
        
                Show Lines

                                                    // ... lines 1 - 15
                            
            return [
        
                Show Lines

                                                    // ... lines 17 - 23
                            
                '@hotwired/stimulus' => [
        
                    'url' => 'https://cdn.jsdelivr.net/npm/@hotwired/stimulus@3.2.1/+esm',
        
                ],
        
                '@symfony/stimulus-bundle' => [
        
                    'path' => '@symfony/stimulus-bundle/loader.js',
        
                ],
        
            ];

Up here, when using a CDN, the entry will have a url key. When pointing to a local file, the entry will have a path key, which will be the logical path to a file in AssetMapper.

But, what does this weird path point to? Spin over to your terminal and run:

php bin/console debug:asset

If you take an elevator to the top... voilà! When we installed StimulusBundle, it added a new "asset path" to our system, which points to vendor/symfony/stimulus-bundle/assets/dist and it has a "Namespace prefix". This means that, to point to a file in this directory, the logical path will start with @symfony/stimulus-bundle.

So over here, when we say @symfony/stimulus-bundle/loader.js, we're referring to this file right here: vendor/symfony/stimulus-bundle/assets/dist/loader.js. That's a long way of saying, when we import @symfony/stimulus-bundle, it's actually importing this vendor/symfony/stimulus-bundle/assets/dist/loader.js file. The bundle exposes that file by adding the AssetMapper "asset path", which allows the recipe to add an entry to importmap.php that points to it.

How our Controllers are Registered

Okay, so we're loading this loader.js file, and we can see that over here. In your browser, refresh... go to your Network tools, and search for "loader". There it is! Open this up in a new tab.

This code has functions to start the Stimulus application and register the controllers from our app - like hello_controller.js. But... wait. This is just a hard-coded file. How is it able to dynamically find and load the files that live inside our assets/controllers/ directory?

The key is on top: import, isApplicationDebug, eagerControllers, lazyControllers from ./controllers.js. This... is a bit of magic. Go back to the Network tools and search for "controllers"... there it is - controllers.js. Open this new tab. Woh! It has import controller_0 from ../../controllers/hello_controller.js, which it then exports to a variable called eagerControllers.

This file is crafted dynamically by the bundle. If we look down in the vendor/ directory, loader.js is a nice static file. But if you look at controllers.js, it doesn't look like at all like what we have in the browser! When this file is served, AssetMapper intercepts it, looks inside of our assets/controllers/ directory, finds all the controllers there, and then returns dynamic contents based on these.

Watch. Create another file called goodbye-controller.js (you can use dashes or underscores). Change the text to Goodbye controller!.

            Copy Code

                        8 lines
            |
            assets/controllers/goodbye_controller.js
        
            import { Controller } from '@hotwired/stimulus';
        
            export default class extends Controller {
        
                connect() {
        
                    this.element.textContent = 'Goodbye controller!';
        
                }
        
            }

You might expect that, when we refresh the file, we'll see the new controller pop in here. And you're almost right. What really happens is... nothing! No change! Or you might even get a 404 error. That's because the content of this file just changed and so the hash will also change. We're looking at an out-of-date version of the file!

Back on the site, if we refresh, we should see a new file with a new hash. We don't... due to a caching bug which has already been fixed. To work around that, I'll run:

php bin/console cache:clear

Then go refresh. Now I see that this has a different file name, and the contents have dynamically changed to include goodbye-controller.js!

So there you have it, the thrilling journey into the heart of how Stimulus and AssetMapper became best friends. bootstrap.js loads a file that starts Stimulus... and that automatically loads everything inside the assets/controllers/ directory... as well as any 3rd party UX packages in assets/controllers.json. Let's talk about those 3rd party packages next.

6 Comments

Sort By

Singollo 5 months ago edited

I had a problem with installing symfony/stimulus-bundle using composer - the composer.lock locked twig on uncompatible version 3.6.1:

Problem 1
    - symfony/stimulus-bundle[v2.18.0, ..., v2.18.1] require twig/twig ^2.15.3|^3.8 -> found twig/twig[v2.15.3, ..., v2.16.0, v3.8.0, ..., v3.10.3] but the package is fixed to v3.6.1 (lock file version) by a partial update and that version does not match. Make sure you list it as an argument for the update command.
    - Root composer.json requires symfony/stimulus-bundle ^2.18 -> satisfiable by symfony/stimulus-bundle[v2.18.0, v2.18.1].

Fortunately, you can simple upgrade twig version: composer update twig/twig and then install stimulus-bundle as described

| Reply |

Victor SFCASTS Singollo 5 months ago edited

Hey @Singollo ,

We use symfony/stimulus-bundle v2.9.1 in the video, so to match the code in the video we recommend you install that exact version. For this, you would need to run:

composer require "symfony/stimulus-bundle:^2.9.1"

That command should work when you follow the tutorial from scratch, but if you already upgraded the twig/twig package - you need to downgrade it. Or you can follow the tutorial on a fresher version, but keen in mind of some possible changes.

The exact versions of packages that are used in the course project code you can easily see on this page:
https://symfonycasts.com/screencast/asset-mapper/stimulus#versions

Cheers!

1 | Reply |

MolloKhan SFCASTS Singollo 5 months ago edited

Hey @Singollo

Thank you for sharing your solution. We'll find a way to avoid that issue from happening in the tutorial code

Cheers!

| Reply |

Lubna 7 months ago

Thank you! All is clear, i was just wondering about how can I import (stimulus-use) for some features like "useClickOutside". Many thanks in advance :)

| Reply |

sadikoff SFCASTS Lubna 7 months ago edited

Hello @Lubna

Easy as any other JS package add it with php bin/console importmap:require 'stimulus-use' and use it as usual.

Cheers!

1 | Reply |

Lubna sadikoff 7 months ago

Just that easy! It works well, thanks a lot and have a nice day!

| Reply |

Symfony 6.3

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "php": ">=8.1",
        "ext-ctype": "*",
        "ext-iconv": "*",
        "babdev/pagerfanta-bundle": "^4.0", // v4.2.0
        "doctrine/doctrine-bundle": "^2.7", // 2.10.0
        "doctrine/doctrine-migrations-bundle": "^3.2", // 3.2.4
        "doctrine/orm": "^2.12", // 2.15.2
        "knplabs/knp-time-bundle": "^1.18", // v1.20.0
        "pagerfanta/doctrine-orm-adapter": "^4.0", // v4.1.0
        "pagerfanta/twig": "^4.0", // v4.1.0
        "stof/doctrine-extensions-bundle": "^1.7", // v1.7.1
        "symfony/asset": "6.3.*", // v6.3.0
        "symfony/asset-mapper": "6.3.*", // v6.3.0
        "symfony/console": "6.3.*", // v6.3.0
        "symfony/dotenv": "6.3.*", // v6.3.0
        "symfony/flex": "^2", // v2.3.1
        "symfony/framework-bundle": "6.3.*", // v6.3.0
        "symfony/http-client": "6.3.*", // v6.3.0
        "symfony/monolog-bundle": "^3.0", // v3.8.0
        "symfony/proxy-manager-bridge": "6.3.*", // v6.3.0
        "symfony/runtime": "6.3.*", // v6.3.0
        "symfony/stimulus-bundle": "^2.9", // v2.9.1
        "symfony/twig-bundle": "6.3.*", // v6.3.0
        "symfony/ux-turbo": "^2.9", // v2.9.1
        "symfony/web-link": "6.3.*", // v6.3.0
        "symfony/yaml": "6.3.*", // v6.3.0
        "twig/extra-bundle": "^2.12|^3.0", // v3.6.1
        "twig/twig": "^2.12|^3.0" // v3.6.1
    },
    "require-dev": {
        "doctrine/doctrine-fixtures-bundle": "^3.4", // 3.4.4
        "symfony/debug-bundle": "6.3.*", // v6.3.0
        "symfony/maker-bundle": "^1.41", // v1.49.0
        "symfony/stopwatch": "6.3.*", // v6.3.0
        "symfony/web-profiler-bundle": "6.3.*", // v6.3.0
        "zenstruck/foundry": "^1.21" // v1.33.0
    }
}

Previous Challenge

Next Chapter

Adding Stimulus

Share this awesome video!

Keep on Learning!

Installing StimulusBundle

How Stimulus Loads

How our Controllers are Registered

6 Comments

Delete comment?

What PHP libraries does this tutorial use?

	import { Controller } from '@hotwired/stimulus';
Show Lines	// ... lines 2 - 11
	export default class extends Controller {
	connect() {
	this.element.textContent = 'Hello Stimulus! Edit me in assets/controllers/hello_controller.js';
	}
	}

Show Lines	// ... lines 1 - 4
	{% block body %}
	<div class="px-4">
Show Lines	// ... line 7
	<div {{ stimulus_controller('hello') }}></div>
Show Lines	// ... lines 9 - 33
	</div>
	{% endblock %}

Show Lines	// ... lines 1 - 2
	<head>
Show Lines	// ... lines 4 - 11
	{% block stylesheets %}
	{{ ux_controller_link_tags() }}
Show Lines	// ... lines 14 - 15
	{% endblock %}
Show Lines	// ... lines 17 - 21
	</head>
Show Lines	// ... lines 23 - 72

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

	const app = startStimulusApp();
Show Lines	// ... lines 4 - 6

Show Lines	// ... lines 1 - 15
	return [
Show Lines	// ... lines 17 - 23
	'@hotwired/stimulus' => [
	'url' => 'https://cdn.jsdelivr.net/npm/@hotwired/stimulus@3.2.1/+esm',
	],
	'@symfony/stimulus-bundle' => [
	'path' => '@symfony/stimulus-bundle/loader.js',
	],
	];