
Web Development · Symfony 8.2 and AssetMapper
Symfony 8.2 modernizes AssetMapper with more targeted import maps, SRI, controlled updates, and new production settings. PHP and Twig examples, plus a testing method.
Do you really need to install and maintain a JavaScript build pipeline for every Symfony application? AssetMapper already lets you serve modern CSS and JavaScript modules without a bundler. With Symfony 8.2, it becomes more compelling for professional websites and business software with multiple entry points: targeted import maps, resource integrity, better-controlled package updates, and more flexible deployment.
Symfony detailed these new features on November 10, 2026. This is not yet the stable release of Symfony 8.2: Symfony 8.2.0-BETA1 has been available since November 4, and the final version is expected in November 2026. This is therefore an ideal time to test their impact without confusing a beta feature with a change already deployed across all Symfony sites.
Here are the six official improvements, a practical example combining a public-facing site and an admin area, a browser-based measurement method, and the cases where Vite or Webpack Encore remain better choices.
Symfony 8.2 introduces the importmap_entries: reachable filter, SRI hashes, and the minimum_release_age option. It also lets you download a raw package file, skip compiled metadata in debug mode, and store metadata outside the public directory. A shorter import map does not automatically mean less JavaScript is downloaded.
The November 10, 2026 publication presents the AssetMapper improvements. They are already included in the changelog for Symfony 8.2.0-BETA1, released on November 4. The Symfony release schedule announces a stable release in November 2026, with no specific date confirmed in the official pages consulted.
Symfony 8.2 requires PHP 8.4 or later. As of November 10, Symfony 8.1 remains the current stable branch, while Symfony 7.4 is a maintained LTS branch. A team using Symfony 7.4 or PHP 8.2/8.3 should therefore not copy this configuration to its current server assuming it will be recognized there.
This guide describes options announced and included in the Symfony 8.2 beta. Final validation of behavior, compatibility, and operating costs must be carried out on the versions actually deployed.
AssetMapper maps logical paths to CSS, JavaScript, image, and other resource files, generates versioned URLs, and relies on the browser’s native import maps to resolve module imports. In a Twig template, {{ importmap('app') }} outputs the elements needed to load the app entry point.
Do not confuse not using a bundler in the delivery pipeline for standard JavaScript modules with having no tooling at all. A TypeScript project may still need a transformation step, and complex React/Vue applications often use their own dedicated frontend tools. AssetMapper does not automatically concatenate or minify files as a traditional build configuration would.
A server-rendered application with multiple pages, a client area, and an admin area can manage targeted scripts and controlled dependencies without a general-purpose bundler.
A rich frontend requiring complex transformations, JSX, or .vue components may still be easier to operate with Vite, Encore, or the chosen framework’s tooling.
| New feature | Purpose | Caveat |
|---|---|---|
importmap_entries: reachable |
Render only entries reachable from the page | Dynamic imports with computed names |
importmap_integrity_algorithms |
Add integrity hashes to resources | Does not replace audits and CSP |
minimum_release_age |
Delay some package updates | Does not apply to importmap:require |
--no-esm |
Download the file provided by the package | Bare imports need resolving, and the file format must be checked |
| No compiled metadata in debug mode | Use source files without manual cleanup | Behavior depends on debug mode |
metadata_dir |
Move PHP metadata outside the public directory | Update the deployment artifact |
Until now, the Twig importmap() call rendered all the entries in importmap.php, even when the page launched just one entry point. A public form could therefore include module definitions reserved for the admin area in its HTML. These definitions did not necessarily mean the modules would be downloaded, but they increased the size of the rendered map and exposed entry-point names that were not needed on that page.
With importmap_entries: reachable, Symfony keeps the entries reachable from the entry points passed to importmap(). The calculation includes static imports and dynamic imports with a known path. However, an import(computedName) cannot be followed statically: this case must be tested or handled differently. The default remains all, specifically to avoid unexpected breakage.
The importmap_integrity_algorithms option generates cryptographic hashes, for example using sha384. When enabled, importmap() adds an integrity entry to the import map and an integrity attribute to the corresponding modulepreload links and stylesheets. Supported algorithms are sha256, sha384, and sha512.
This verification helps protect against tampering with loaded files, but it does not prove that a package is safe: a file compromised when its hash is calculated remains compromised. It does not replace Content Security Policy, dependency reviews, or application-level controls.
The minimum_release_age option is expressed in seconds. A value of 604800 imposes a seven-day delay for eligible versions during importmap:update. Symfony also ignores prereleases and certain versions beyond the latest tag. The importmap:outdated command displays a Withheld column for versions being held back.
This safeguard is not a universal fix for supply-chain attacks: it is intended to avoid immediately adopting every newly published version. Most importantly, importmap:require is not subject to this delay. Checks now download complete npm metadata to determine publication dates, which may make this step heavier.
--no-esmBy default, AssetMapper uses the ESM transformation provided by jsDelivr for fetched dependencies. If this transformation causes problems, the new --no-esm option requests the file published by the package itself. You must provide the exact path to the file to import.
Symfony then handles relative imports such as ./chunk.js, but does not automatically resolve bare imports such as import { h } from 'preact': the corresponding packages must be added explicitly. Downloading a raw file does not guarantee that it is compatible with a native ESM import; check the format published by the author.
In previous versions, running asset-map:compile on your machine could leave compiled metadata that took precedence over source files during development. JavaScript/CSS changes then appeared not to take effect until you deleted public/assets/. In Symfony 8.2, when debug mode is enabled, this metadata is ignored in favor of the source files. This makes it easier to switch between build tests and development.
public/asset-map:compile generates files including manifest.json, importmap.json, and entrypoint.*.json files. PHP reads this metadata, but its default location in the public assets directory makes it accessible over HTTP. The new metadata_dir parameter lets you place it somewhere like var/assets.
This move makes it easier to organize artifacts. However, you must check that the PHP process can read this directory and that the deployment procedure preserves or regenerates it. This does not turn metadata into a secret vault: no confidential data should be stored there.
Consider a Symfony application with a lightweight public-facing section and an admin area with tables and interactive components. We want to avoid rendering JavaScript definitions specific to the admin area in the import map for a public page. The following snippets illustrate the principle; adapt them to your project’s asset names and dependencies.
For a project that does not yet have AssetMapper, the documented installation is:
composer require symfony/asset-mapper symfony/asset symfony/twig-pack
php bin/console debug:asset-map
With Symfony Flex, this creates files including assets/app.js and importmap.php, as well as an importmap('app') call in the template. For our scenario, add the assets/admin.js file and declare two entry points:
<?php
// importmap.php
return [
'app' => [
'path' => './assets/app.js',
'entrypoint' => true,
],
'admin' => [
'path' => './assets/admin.js',
'entrypoint' => true,
],
];
In a real application, keep any existing dependency entries in importmap.php as well: this snippet deliberately shows only the entry points.
The base template loads app. For the admin area, load both entry points with a single call to importmap():
{# templates/base.html.twig #}
{% block javascripts %}
{% block importmap %}
{{ importmap('app') }}
{% endblock %}
{% endblock %}
{# templates/admin/dashboard.html.twig #}
{% extends 'base.html.twig' %}
{% block importmap %}
{{ importmap(['app', 'admin']) }}
{% endblock %}
Do not call parent() in this Twig block: the import map should be rendered just once on the page. The imports from the admin entry point will not be executed on a page that loads only app.
On a test branch using Symfony 8.2, you can group the settings in config/packages/asset_mapper.yaml:
# config/packages/asset_mapper.yaml
framework:
asset_mapper:
importmap_entries: reachable
importmap_integrity_algorithms: ['sha384']
minimum_release_age: 604800
metadata_dir: '%kernel.project_dir%/var/assets'
These four options serve different purposes: reachable changes the contents of the page’s import map; sha384 adds hashes; minimum_release_age applies during updates; metadata_dir controls where compiled metadata is stored. They are not a single “improve performance” switch.
Modules imported using a literal path are tracked:
// assets/app.js
document.querySelector('#open-help')?.addEventListener('click', async () => {
const module = await import('./help-panel.js');
module.openHelp();
});
By contrast, the following case relies on a computed expression whose possible values Symfony cannot determine during analysis:
// Audit this before choosing importmap_entries: reachable
const name = window.currentWidgetName;
const widget = await import(name);
If the application contains computed imports or plugins loaded from dynamic configuration, explicitly test all relevant paths, or temporarily keep the all behavior until the application is adapted.
You can begin a dependency review with:
php bin/console importmap:outdated
php bin/console importmap:audit
# Update only after validation
php bin/console importmap:update
Starting with Symfony 8.2, the importmap:outdated command lets you see versions temporarily held back by the minimum-age delay. For a package whose jsDelivr-generated ESM transformation fails, Symfony provides this example:
php bin/console importmap:require "fullcalendar/index.global.js=fullcalendar" --no-esm
Then check that the provided file is actually compatible, especially if it is a global build rather than an ES module. Being able to retrieve a file does not ensure that its API can be imported as a native JavaScript export.
The compilation step still generates versioned assets for the web server:
APP_ENV=prod APP_DEBUG=0 php bin/console asset-map:compile
If metadata is moved to var/assets, check the path on the final server, PHP’s read permissions, and the presence of the files in the deployment artifact. Development behavior does not replace the need to compile or correctly expose resources in production.
The first measurement to make is not a Lighthouse score: it is the difference in import map contents with the default all option and with reachable. Then compare the preloaded resources, the JavaScript actually transferred, and the user experience.
type="importmap" script and count the entries it contains.You can inspect the map in the browser console without installing an additional library:
const element = document.querySelector('script[type="importmap"]');
if (element) {
const map = JSON.parse(element.textContent);
console.table({
imports: Object.keys(map.imports ?? {}).length,
htmlCharacters: element.textContent.length
});
}
This small diagnostic shows the number of module definitions and the map’s text length, not the total size of downloaded files. An import map can contain 100 entries even if a page runs only one module. To claim a network or Core Web Vitals improvement, you need to see a change in requests or browser workload, not just count fewer lines of HTML.
Reducing unnecessary code, improving loading, and simplifying dependencies can contribute to a better user experience. But no AssetMapper change alone guarantees better SEO rankings. Measurements should be based on real-world data and actual user journeys.
An upgrade to Symfony 8.2 should begin with the technical foundation: PHP 8.4 minimum, bundle versions, Flex recipes, AssetMapper configuration, and automated tests. Moving from Symfony 8.1 to 8.2 is different from migrating from an older LTS branch, which may require intermediate steps.
Symfony provides the following prerelease procedure for a project whose dependency constraints allow it:
# Only on a dedicated test branch
composer config minimum-stability beta
composer config extra.symfony.require "8.2.*"
composer update
Caution: these commands change Composer’s dependency resolution and should not be run as-is in production. The beta announcement notes that they assume compatible Symfony constraints in composer.json; otherwise, those constraints need to be adjusted. Also check composer.lock, your tests, and your rollback plan.
reachable separately. Validate every entry point and dynamic import, including those used by Stimulus controllers.integrity attributes, ensure there are no loading errors, and review existing CSP rules.minimum_release_age, known vulnerabilities, and urgent exceptions.It is often more useful to test one option at a time than to enable every setting at once: this makes it easier to identify measurable effects and potential regressions.
| Criterion | AssetMapper | Vite or Encore |
|---|---|---|
| Symfony/Twig site with moderate JavaScript | Often easy to maintain | Possible, but may add a build step |
| Import maps and native ES modules | Core to the approach | Not necessarily used in production |
| TypeScript | Transformation via a dedicated tool/bundle | Integrated into the frontend pipeline, depending on configuration |
| Vue SFCs, JSX, complex transformations | Less straightforward | Often a better fit |
| Fine-grained bundling control | No native bundling | Configurable bundling and optimization |
| Long-term maintenance | May mean less Node tooling to operate, depending on the project | Rich ecosystem, but build dependencies need to be maintained |
For business software rendered mostly on the server, AssetMapper can reduce the number of components to manage. For a dashboard built as an SPA or requiring advanced frontend transformations, not having a bundler is not an end in itself: Vite or Encore may make the project easier to understand.
SDX’s recommendation: start with your use cases, team, and maintenance costs. The Symfony 8.2 improvements make AssetMapper more flexible for multipage applications, but they do not make other frontend tools obsolete.
No. It already exists and is used in production in earlier versions. The new development on November 10, 2026, was the detailed announcement of six improvements planned for Symfony 8.2.
Not as of November 10, 2026. Symfony 8.2.0-BETA1 was released on November 4; the stable version is expected in November and requires PHP 8.4 or later.
Not necessarily. It reduces the module definitions rendered for a page. Which modules are actually loaded depends on the imports that run and on preloads. Check the network requests.
minimum_release_age block all new dependencies?No. It limits some updates made by importmap:update. It is not applied to importmap:require and does not replace a dependency audit.
AssetMapper serves JavaScript modules. TypeScript requires a transformation step. Symfony points to a dedicated bundle, among other options, so you need to assess the required tooling for your project.
No. It lets you verify the integrity of resources served to the browser, but not whether they were safe when published. Keep version controls, audits, CSP, and code reviews in place.
WEB DEVELOPMENT
PHP migration, CMS update or framework evolution: identify compatibility points and validate essential user journeys before going live.
Enter at least 2 characters to start searching.