AssetMapper: Simple, Modern CSS & JS Management (Symfony Docs)

The AssetMapper component lets you write modern JavaScript and CSS without the complexity of using a bundler. Browsers already support many modern JavaScript features like the import statement and ES6 classes. And the HTTP/2 protocol means that combining your assets to reduce HTTP connections is no longer urgent. This component is a light layer that helps serve your files directly to the browser.
The component has two main features:
To install the AssetMapper component, run:
In addition to symfony/asset-mapper, this also makes sure that you have the Asset Component and Twig available.
If you're using Symfony Flex, you're done! The recipe just added a number of files:
It also updated the templates/base.html.twig file:
If you're not using Flex, you'll need to create & update these files manually. See the latest asset-mapper recipe for the exact content of these files.
The AssetMapper component works by defining directories/paths of assets that you want to expose publicly. These assets are then versioned and easy to reference. Thanks to the asset_mapper.yaml file, your app starts with one mapped path: the assets/ directory.
If you create an assets/images/duck.png file, you can reference it in a template with:
The path - images/duck.png - is relative to your mapped directory (assets/). This is known as the logical path to your asset.
If you look at the HTML in your page, the URL will be something like: /assets/images/duck-3c16d92m.png. If you change the file, the version part of the URL will also change automatically.
In the dev environment, the URL /assets/images/duck-3c16d92m.png is handled and returned by your Symfony app. For the prod environment, before deploy, you'll run a command to write the final versioned files into public/assets/ so that they're served directly by your web server. See Compiling Assets for more details.
To see all of the mapped assets in your app, run:
This will show you all the mapped paths and the assets inside of each:
The "Logical Path" is the path to use when referencing the asset, like from a template.
The debug:asset-map command provides several options to filter results:
All modern browsers support the JavaScript import statement and modern ES6 features like classes. So this code "just works":
Thanks to the {{ importmap('app') }} Twig function call, which you'll learn about in this section, the assets/app.js file is loaded & executed by the browser.
When importing relative files, be sure to include the .js filename extension. Unlike in Node.js, this extension is required in the browser environment.
All of this works thanks to the {{ importmap() }} Twig function in base.html.twig, which outputs an importmap (shown here with a third-party bootstrap package, which you'll learn to add later in this article):
Import maps are a native browser feature. When you import bootstrap from JavaScript, the browser will look at the importmap and see that it should fetch the package from the associated path.
But where did the /assets/duck.js import entry come from? That doesn't live in importmap.php.
The assets/app.js file above imports ./duck.js. When you import a file using a relative path, your browser looks for that file relative to the one importing it. So, it would look for /assets/duck.js. That URL would be correct, except that the duck.js file is versioned. Fortunately, the AssetMapper component sees the import and adds a mapping from /assets/duck.js to the correct, versioned filename. The result: importing ./duck.js just works!
The importmap() function also outputs an ES module shim so that older browsers understand importmaps (see the polyfill config).
An "entrypoint" is the main JavaScript file that the browser loads. Most projects only need the single app entrypoint that your app starts with by default, but you can create additional ones - for example, to load JavaScript or CSS only on a specific page, as shown in Page-Specific CSS & JavaScript:
In addition to the importmap, the {{ importmap('app') }} in base.html.twig outputs a few other things, including:
This line tells the browser to load the app importmap entry, which causes the code in assets/app.js to be executed.
The importmap() function also outputs a set of "preloads":
This is a performance optimization and you can learn more about it below in Performance: Add Preloading.
Features like importmaps and the import statement are supported in all modern browsers, and the AssetMapper component ships with an ES module shim to support importmap in old browsers. So, it works everywhere (see note below).
Inside your own code, if you're relying on modern ES6 JavaScript features like the class syntax, this is supported in all but the oldest browsers. If you do need to support very old browsers, you should use a tool like Encore instead of the AssetMapper component.
The import statement can't be polyfilled or shimmed to work on every browser. However, only the oldest browsers don't support it.
The importmap feature is shimmed to work in all browsers by the AssetMapper component (using es-module-shims). However, this shim only polyfills import map support; it does not polyfill the import() syntax itself, which is a native JavaScript feature.
AssetMapper correctly rewrites dynamic imports when the path is a string literal:
Browsers without native import support will fail regardless of AssetMapper. For those browsers, you can use the importShim() function provided by the shim.
If you use a transpiler (e.g. Babel, TypeScript) that transforms import() calls, make sure to run it before AssetMapper compiles the assets. Otherwise the file hashes will change after transpilation and the versioned URLs will break.
Suppose you want to use an npm package, like bootstrap. Technically, this can be done by importing its full URL, like from a CDN:
But yikes! Needing to include that URL is a pain! Instead, you can add this package to your "importmap" via the importmap:require command. This command can be used to add any npm package: