Installation

First, install AssetMapper as explained in the AssetMapper documentation (for
us, it was just running composer require symfony/asset-mapper command and
checking the changes done by the associated recipe).

The importmap.php File

Instead of using the webpack.config.js file, in AssetMapper you use a file
called importmap.php at the root directory of the project. This file tells
which assets are used in your application.

Instead of creating this file by hand, you run the importmap:require command
and add all the needed assets. In our case, we took the list of assets in the
package.json file and added the dependencies one by one with the
importmap:require command:

Keep in mind that you don’t have to install the dependencies that were used only
by Webpack Encore and not your application (in our case: @babel/core,
@babel/preset-env, file-loader, webpack, etc.)

If you open the importmap.php after installing the assets, you’ll see something
like this:

This file only defines the versions of the assets. To actually download the assets,
you must run the importamp:install command, which downloads the assets to
the <your-project>/assets/vendor/ directory. This is like the old node_modules/
directory, but if you compare both, you’ll see that the new assets vendor only
contains a few files. This is because AssetMapper downloads the full compiled
CSS/JavaScript files, instead of all the source files needed to build them.

The Entrypoints

In the webpack.config.js file you defined the Webpack Encore entries,
which are the final asset files that will be generated when building assets:

In AssetMapper there’s a similar concept called entrypoints. When upgrading
to AssetMapper, we mapped the entries into entrypoints 1-to-1. You need to
do this manually by editing the importmap.php file:

We realized that we probably have too many entrypoints. This is because, in the
past, we wanted to load on each page the smallest amount of CSS/JavaScript possible.
So, we created an entry for each significant page and loaded only what that page
needed. Nowadays, thanks to the massive compression of web assets, this is not
worth it for normal pages. So, we’ll remove some entrypoints in the future and
leave only the entrypoints of very complex pages.

Changes in Asset Files

Your files inside the assets/ directory don’t require many changes, but you
might need to do some tweaks. Now, every time you import files, you must include
the file extension:

Another tweak we made is in the way we load the Bootstrap CSS styles. Before,
we used to pick and choose which parts of Bootstrap to use:

We did this to optimize assets as much as possible and only include the parts
that we’re going to use. Now we include the entire Bootstrap CSS styles:

This is an acceptable trade-off for us because we use most of the Bootstrap CSS
styles and because, thanks to compression, browsers only need to download 34 KB
to get the full Bootstrap styles.

Changes in Templates

Our templates followed a very typical hierarchy and loaded Webpack Encore entries
like this:

All pages need the app.css and app.js assets, so we load the app
entry in the base.html.twig template. Then, if any template needs additional
assets, they load other Webpack Encore entries using Twig template inheritance.

Now, the same templates look like this:

Now it looks much simpler, because you only need to importmap() one entrypoint
to get both the CSS and JavaScript files. However, there’s a drawback. You can’t
use template inheritance to add more entrypoints to the page. You can only call
importmap() once per page. So, the base entrypoints used by all pages (e.g.
app) must be repeated in all the importmap() calls of the templates
that add new entrypoints.

Saas and CSS

We used Sass in all the applications instead of pure CSS. Sass served us well
during these years, but we no longer need it. The only two Sass features that we
used were:

Variables: no longer needed thanks to CSS custom properties;
Nested selectors: no longer needed thanks to CSS nesting.

In most websites, we refactored the Sass files into pure CSS files. Given that
CSS nesting is still at 80% browser support, we removed nested selectors and
we’ll add them back again when support is more widespread.

In another website, we kept the .scss files because moving to CSS was too
much work. In that project, we installed the symfonycasts/sass-bundle which
makes it easy to use Sass with Symfony’s AssetMapper Component (it doesn’t require
using Node.js).

Tailwind CSS

In some website, we use Tailwind CSS instead of Bootstrap. Luckily, there’s
a symfonycasts/tailwind-bundle that takes care of everything for you. This
bundle doesn’t require Node.js either and it’s based on a binary file that
compiles the Tailwind CSS styles.

Changes in CI and Deployment

This was one of the easiest parts of the upgrade process. You only need to update
the commands run to build/compile the assets:

The deployment process required zero changes. Thanks to its tight integration
with Symfony, Platform.sh already detects if you are using AssetMapper, SassBundle
and/or TailwindBundle and runs the required commands for you.