AssetMapper: Simple, Modern CSS & JS Management

Serving Assets in dev vs prod

In the dev environment, the URL /assets/images/duck-3c16d9220694c0e56d8648f25e6035e9.png is handled and returned by your Symfony app.

For the prod environment, before deploy, you should run:

1

$ php bin/console asset-map:compile

This will physically copy all the files from your mapped directories to public/assets/ so that they're served directly by your web server. See Deployment for more details.

Paths Inside of CSS Files

From inside CSS, you can reference other files using the normal CSS url() function and a relative path to the target file:

1
2
3
4
5

/* assets/styles/app.css */
.quack {
    /* file lives at assets/images/duck.png */
    background-image: url('../images/duck.png');
}

The path in the final app.css file will automatically include the versioned URL for duck.png:

1
2
3
4

/* public/assets/styles/app-3c16d9220694c0e56d8648f25e6035e9.css */
.quack {
    background-image: url('../images/duck-3c16d9220694c0e56d8648f25e6035e9.png');
}

Debugging: Seeing All Mapped Assets

To see all of the mapped assets in your app, run:

1

$ php bin/console debug:asset-map

This will show you all the mapped paths and the assets inside of each:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

AssetMapper Paths
------------------

--------- ------------------
 Path      Namespace prefix
--------- ------------------
assets

Mapped Assets
-------------

------------------ ----------------------------------------------------
 Logical Path       Filesystem Path
------------------ ----------------------------------------------------
 app.js             assets/app.js
 styles/app.css     assets/styles/app.css
 images/duck.png    assets/images/duck.png

The "Logical Path" is the path to use when referencing the asset, like from a template.

Importing 3rd Party JavaScript Packages

Suppose you want to use an npm package, like bootstrap. Technically, this can be done by importing its full URL, like from a CDN:

1

import { Alert } from 'https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/+esm';

But yikes! Needing to include that URL is a pain! Instead, we can add this to our "importmap" via the importmap:require command. This command can be used to download any npm package:

1

$ php bin/console importmap:require bootstrap

This adds the bootstrap package to your importmap.php file:

1
2
3
4
5
6
7
8

// importmap.php
return [
    // ...

    'bootstrap' => [
        'url' => 'https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/+esm',
    ],
];

Now you can import the bootstrap package like normal:

1
2

import { Alert } from 'bootstrap';
// ...

If you want to download the package locally, use the --download option:

1

$ php bin/console importmap:require bootstrap --download

This will download the package into an assets/vendor/ directory and update the importmap.php file to point to it. You should commit this file to your repository.

To update all 3rd party packages in your importmap.php file, run:

1

$ php bin/console importmap:update

How does the importmap Work?

How does this importmap.php file allow you to import bootstrap? That's thanks to the {{ importmap() }} Twig function in base.html.twig, which outputs an importmap:

1
2
3
4
5
6
7

<script type="importmap">{
    "imports": {
        "app": "/assets/app-4e986c1a2318dd050b1d47db8d856278.js",
        "/assets/duck.js": "/assets/duck-1b7a64b3b3d31219c262cf72521a5267.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/+esm"
    }
}</script>

Import maps are a native browser feature. They work in all browsers thanks to a "shim" file that's included automatically by the AssetMapper component (all modern browsers support them natively).

When you import bootstrap from your JavaScript, the browser will look at the importmap and see that it should fetch the package from the URL.

But where did the /assets/duck.js import entry come from? Great question!

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 that import and adds a mapping from /assets/duck.js to the correct, versioned filename. The result: importing ./duck.js just works!

Preloading and Initializing "app.js"

In addition to the importmap, the {{ importmap() }} Twig function also renders an ES module shim (see the polyfill config) and a few other things, like a set of "preloads":

1
2

<link rel="modulepreload" href="/assets/app-4e986c1a2318dd050b1d47db8d856278.js">
<link rel="modulepreload" href="/assets/duck-1b7a64b3b3d31219c262cf72521a5267.js">

In importmap.php, each entry can have a preload option. If set to true, a <link rel="modulepreload"> tag is rendered for that entry as well as for any JavaScript files it imports (this happens for "relative" - ./ or ../ - imports only). This is a performance optimization and you can learn more about below in Performance: Add Preloading.

The importmap() function also renders one more line:

1

<script type="module">import 'app';</script>

So far, the snippets shown export an importmap and even hinted to the browser that it should preload some files. But the browser hasn't yet been told to actually parse and execute any JavaScript. This line does that: it imports the app entry, which causes the code in assets/app.js to be executed.

Importing Specific Files From a 3rd Party Package

Sometimes you'll need to import a specific file from a package. For example, suppose you're integrating highlight.js and want to import just the core and a specific language:

1
2
3
4
5

import hljs from 'highlight.js/lib/core';
import javascript from 'highlight.js/lib/languages/javascript';

hljs.registerLanguage('javascript', javascript);
hljs.highlightAll();

In this case, adding the highlight.js package to your importmap.php file won't work: whatever your importing - e.g. highlight.js/lib/core - needs to exactly match an entry in the importmap.php file.

Instead, use importmap:require and pass it the exact paths you need. This also shows how you can require multiple packages at once:

1

$ php bin/console importmap:require highlight.js/lib/core highlight.js/lib/languages/javascript

Global Variables like jQuery

You might be accustomed to relying on global variables - like jQuery's $ variable:

1
2
3
4
5

// assets/app.js
import 'jquery';

// app.js or any other file
$('.something').hide(); // WILL NOT WORK!

But in a module environment (like with AssetMapper), when you import a library like jquery, it does not create a global variable. Instead, you should import it and set it to a variable in every file you need it:

1
2

import $ from 'jquery';
$('.something').hide();

You can even do this from an inline script tag:

1
2
3
4

<script type="module">
    import $ from 'jquery';
    $('.something').hide();
</script>

If you do need something to become a global variable, you do it manually from inside app.js:

1
2
3

import $ from 'jquery';
// things on "window" become global variables
window.$ = $;

Lazily Importing CSS from a JavaScript File

When using a bundler like Encore, you can import CSS from a JavaScript file:

1
2

// this CAN work (keep reading), but will be loaded lazily
import 'swiper/swiper-bundle.min.css';

This can work with importmaps, but it should not be used for critical CSS that needs to be loaded before the page is rendered because the browser won't download the CSS until the JavaScript file executed.

However, if you do want to lazily-load a CSS file, you can make this work by using the importmap:require command and pointing it at a CSS file.

1

$ php bin/console importmap:require swiper/swiper-bundle.min.css

This works because jsdelivr returns a URL to a JavaScript file that, when executed, adds the CSS to your page.

Missing importmap Entry

One of the most common errors will come from your browser's console, and will something like this:

Failed to resolve module specifier " bootstrap". Relative references must start with either "/", "./", or "../".

Or:

The specifier "bootstrap" was a bare specifier, but was not remapped to anything. Relative module specifiers must start with "./", "../" or "/".

This means that, somewhere in your JavaScript, you're importing a 3rd party package - e.g. import 'bootstrap'. The browser tries to find this package in your importmap file, but it's not there.

The fix is almost always to add it to your importmap:

1

$ php bin/console importmap:require bootstrap

404 Not Found for a JavaScript, CSS or Image File

Sometimes a JavaScript file you're importing (e.g. import './duck.js'), or a CSS/image file you're referencing won't be found, and you'll see a 404 error in your browser's console. You'll also notice that the 404 URL is missing the version hash in the filename (e.g. a 404 to /assets/duck.js instead of a path like /assets/duck.1b7a64b3b3d31219c262cf72521a5267.js).

This is usually because the path is wrong. If you're referencing the file directly in a Twig template:

1

<img src="{{ asset('images/duck.png') }}">

Then the path that you pass asset() should be the "logical path" to the file. Use the debug:asset-map command to see all valid logical paths in your app.

More likely, you're importing the failing asset from a CSS file (e.g. @import url('other.css')) or a JavaScript file:

1
2

// assets/controllers/farm-controller.js
import '../farm/chicken.js';

When doing this, the path should be relative to the file that's importing it (and, in JavaScript files, should start with ./ or ../). In this case, ../farm/chicken.js would point to assets/farm/chicken.js. To see a list of all invalid imports in your app, run:

1
2

$ php bin/console cache:clear
$ php bin/console debug:asset-map

Any invalid imports will show up as warnings on top of the screen (make sure you have symfony/monolog-bundle installed):

1
2

WARNING   [asset_mapper] Unable to find asset "../images/ducks.png" referenced in "assets/styles/app.css".
WARNING   [asset_mapper] Unable to find asset "./ducks.js" imported from "assets/app.js".

Missing Asset Warnings on Commented-out Code

The AssetMapper component looks in your JavaScript files for import lines so that it can automatically add them to your importmap. This is done via regex and works very well, though it isn't perfect. If you comment-out an import, it will still be found and added to your importmap. That doesn't harm anything, but could be surprising.

If the imported path cannot be found, you'll see warning log when that asset is being built, which you can ignore.

Performance: Add Preloading

One common issue that LightHouse may report is:

Avoid Chaining Critical Requests

Some items in this list are fine. But if this list is long or some items are multiple-levels deep, that is something you should fix with "preloading". To understand the problem, imagine that you have this setup:

• assets/app.js imports ./duck.js
• assets/duck.js imports bootstrap

When the browser downloads the page, this happens:

1. The browser downloads assets/app.js;
2. It then sees the ./duck.js import and downloads assets/duck.js;
3. It then sees the bootstrap import and downloads assets/bootstrap.js.

Instead of downloading all 3 files in parallel, the browser is forced to download them one-by-one as it discovers them. This hurts performance. To fix this, in importmap.php, add a preload key to the app entry, which points to the assets/app.js file. Actually, this should already be done for you:

1
2
3
4
5
6
7
8

// importmap.php
return [
    'app' => [
        'path' => 'app.js',
        'preload' => true,
    ],
    // ...
];

Thanks to this, the AssetMapper component will render a "preload" tag onto your page for assets/app.js and any other JavaScripts files that it imports using a relative path (i.e. starting with ./ or ../):

1
2

<link rel="preload" href="/assets/app.js" as="script">
<link rel="preload" href="/assets/duck.js" as="script">

This tells the browser to start downloading both of these files immediately, even though it hasn't yet seen the import statement for assets/duck.js

You'll also want to preload bootstrap as well, which you can do in the same way:

1
2
3
4
5
6
7
8

// importmap.php
return [
    // ...
    'bootstrap' => [
        'path' => '...',
        'preload' => true,
    ],
];

Does the AssetMapper Component Combine Assets?

Nope! But that's because this is no longer necessary!

In the past, it was common to combine assets to reduce the number of HTTP requests that were made. Thanks to advances in web servers like HTTP/2, it's typically not a problem to keep your assets separate and let the browser download them in parallel. In fact, by keeping them separate, when you update one asset, the browser can continue to use the cached version of all of your other assets.

See Optimization for more details.

Does the AssetMapper Component Minify Assets?

Nope! Minifying or compressing assets is important, but can be done by your web server or a service like Cloudflare. See Optimization for more details.

Is the AssetMapper Component Production Ready? Is it Performant?

Yes! Very! The AssetMapper component leverages advances in browser technology (like importmaps and native import support) and web servers (like HTTP/2, which allows assets to be downloaded in parallel). See the other questions about minimization and combination and Optimization for more details.

The https://ux.symfony.com site runs on the AssetMapper component and has a 99% Google Lighthouse score.

Does the AssetMapper Component work in All Browsers?

Yup! Features like importmaps and the import statement are supported in all modern browsers, but 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.

1
2
3
4
5
6
7

// this works
import { add } from './math.js';

// this will not work in the oldest browsers
import('./math.js').then(({ add }) => {
    // ...
});

Can I Use with Sass or Tailwind?

Sure! See Using Tailwind CSS or Using Sass.

Can I use with TypeScript, JSX or Vue?

Probably not.

TypeScript, by its very nature, requires a build step.

JSX can be compiled directly to a native JavaScript file but if you're using a lot of JSX, you'll probably want to use a tool like Encore. See the UX React Documentation for more details about using with the AssetMapper component.

Vue files can be written in native JavaScript, and those will work with the AssetMapper component. But you cannot write single-file components (i.e. .vue files) with component, as those must be used in a build system. See the UX Vue.js Documentation for more details about using with the AssetMapper component.

Overriding 3rd-Party Assets

If you want to override a 3rd-party asset, you can do that by creating a file in your assets/ directory with the same name. For example, if you want to override the pagerfanta.css file, create a file at assets/bundles/babdevpagerfanta/css/pagerfanta.css. This file will be used instead of the original file.

framework.asset_mapper.paths

This config holds all of the directories that will be scanned for assets. This can be a simple list:

1
2
3
4
5

framework:
    asset_mapper:
        paths:
            - assets/
            - vendor/some/package/assets

Of you can give each path a "namespace" that will be used in the asset map:

1
2
3
4
5

framework:
    asset_mapper:
        paths:
            assets/: ''
            vendor/some/package/assets/: 'some-package'

In this case, the "logical path" to all of the files in the vendor/some/package/assets/ directory will be prefixed with some-package - e.g. some-package/foo.js.

framework.asset_mapper.excluded_patterns

This is a list of glob patterns that will be excluded from the asset map:

1
2
3
4

framework:
    asset_mapper:
        excluded_patterns:
            - '*/*.scss'

You can use the debug:asset-map command to double-check that the files you expect are being included in the asset map.

framework.asset_mapper.importmap_polyfill

Configure the polyfill for older browsers. Default is ES module shim. You can pass any URL to be included, or false to disable the polyfill.

1
2
3
4

framework:
    asset_mapper:
        importmap_polyfill: false # disable the shim ...
        # importmap_polyfill: 'https://...' # ... or pass some custom URL

framework.asset_mapper.importmap_script_attributes

This is a list of attributes that will be added to the <script> tags rendered by the {{ importmap() }} Twig function:

1
2
3
4

framework:
    asset_mapper:
        importmap_script_attributes:
            crossorigin: 'anonymous'