Symfony AssetMapper

The Symfony AssetMapper component exposes directories of frontend assets and makes them available in a public directory with digested, versioned filenames for cache-busting. Crucially, it lets you write modern JavaScript using ECMAScript modules and import maps without a Node.js-based build step.

AssetMapper maps logical asset paths to versioned public URLs, rewrites relative imports in JavaScript and CSS, and can generate an importmap plus preload links so browsers resolve bare module specifiers natively. It is the default frontend asset approach in modern Symfony applications, replacing the need for Webpack or similar bundlers for many projects.

What You Get

• Content-hashed, versioned public filenames for automatic cache-busting
• An importmap generator so browsers resolve bare ES module imports without bundling
• Automatic rewriting of relative JavaScript and CSS imports to versioned paths
• A dev-time server subscriber that serves mapped assets during development
• Console commands to compile/dump assets and inspect the asset map

Common Use Cases

• Serving versioned CSS and JavaScript in a Symfony app without Webpack or a Node.js toolchain
• Writing modern ES-module JavaScript that runs directly in the browser via an import map
• Cache-busting static assets with content-hashed filenames
• Pulling third-party JavaScript packages into an importmap for a build-free frontend

Under The Hood

Architecture - The component centers on AssetMapper (AssetMapper.php) implementing AssetMapperInterface, backed by an AssetMapperRepository that discovers files and a MappedAsset model carrying logical path, digested path, and content. An AssetMapperCompiler runs a chain of compilers (Compiler/) that rewrite JavaScript imports, CSS url()s, and source-map references. The ImportMap namespace builds and resolves import maps, a Compressor pre-compresses output, and an AssetMapperDevServerSubscriber serves assets during development.

Tech Stack - PHP (>=8.4.1) packaged as a Symfony component with PSR-4 autoloading under Symfony\Component\AssetMapper. It depends on composer/semver, symfony/filesystem, and symfony/http-client, and integrates optionally with console, framework-bundle, http-kernel, and web-link.

Code Quality - As a core Symfony component it follows Symfony’s rigorous standards: a comprehensive PHPUnit suite under Tests/, clear separation of factories, compilers, and path resolution, and continuous integration in the main symfony/symfony monorepo (this repository is a read-only subtree split).

API Design - Application developers rarely touch the classes directly; the component is consumed declaratively through Symfony configuration and Twig helpers, with console commands for compiling and debugging. The importmap-based workflow removes bundler configuration entirely, dramatically lowering the barrier to shipping modern JavaScript.