[AssetMapper] and framework assets version

[mathielen]

Symfony version(s) affected

6.4+

Description

I am migrating some code from using webpack encore to assetmapper.
I found a very strange behavior and debugged it for a long time. Everything seems to work with assetmapper but the browser still shows a 404 error when importing relative js and css files from app.js like this:

...
//this is for symfony ux
import './bootstrap.js';
...

When looking at the network tab in the browser it would still download the bootstrap.js file (with the correct version hash). And also the importmap looked good:

<script type="importmap">
{
    "imports": {
...
        "/assets/bootstrap.js?v=dev": "/assets/bootstrap-209b7ad405377c6efaf2dffd7b3feba1.js?v=dev",
...

What I did not saw at first (as I'm new to assetmapper) - there is a ?v=dev in the urls. That didnt bother me too much.
Turns out, that was the problem.

Because when you activate asset versioning with the symfony framework like here: https://symfony.com/doc/current/reference/configuration/framework.html#version
it adds the version string to all the generated urls. Which then doesnt match with actual URLs from the in-browser executed app.js anymore.
My framework/assets configuration looked like this:

framework:
  assets:
    version: 'dev'
    version_format: '%%s?v=%%s'

Disabling the whole assets configuration solved my problem.

It might be a good thing to point to this problem in the documentation of assetmapper or somehow solve this so the url-generation in importmap would not use the asset versioning feature even if its turned on.

Cheers
Markus

How to reproduce

1. Use basic Assetmapper set up
2. Enable asset versioning:

in config/packages/framework.yml

framework:
  assets:
    version: 'dev'
    version_format: '%%s?v=%%s'

3. Import a relative file in app.js

...
//this is for symfony ux
import './bootstrap.js';
...

4. See 404 errors in the browser

Possible Solution

Disable framework asset versioning.

Additional Context

No response

[smnandre]

According to the AssetMapper documentation

The AssetMapper component has two main features:
- Mapping & Versioning Assets [...]
- Importmaps [...]

So generally, you should not use asset versionning and AssetMapper at the same time.

Why AssetMapper does not ignore assets configuration ? Because local asset packages is the best way to configure custom pathes, directories, etc.

In fact, internally, AssetMapper uses a dedicated Asset package to handle all your assets.

That's why it is impacted by the global setting you defined in the configuration.

In your case, i think you could configure your "dev" versionning only for some directories by using packages (same thing described in version-strategy) and not globally.

But there is probably something to add in the documentation :)

[mathielen]

Yes, right.

So with 2 competing functionalities it would be nice to have a warning in the logs or some heads-up info in the documentation.

I guess I wont be the only one coming from webpack encore with asset versioning activated and wonder why this doesnt work as expected.

All in all its totally understandable why this is happening as it does - once it is understood how assetmapper, importmaps, etc is actually working.

[carsonbot]

Hey, thanks for your report!
There has not been a lot of activity here for a while. Is this bug still relevant? Have you managed to find a workaround?

[mathielen]

Workaround is to just disable asset versioning. So there is no actual issue anymore. Only room for improvement.

[ttk]

I think this issue should be reopened. I have a legacy app that uses asset versioning, and I want to introduce asset mapper on certain new routes and progressively upgrade old routes as time permits. However, as mentioned earlier in the thread, asset mapper is currently incompatible with asset versioning. For me, disabling asset versioning isn't an option.

I've tried to find a nice workaround, but I don't think there is any elegant solution without having to modify the asset-mapper core functionality.

This is the best I came up with:

In service.yaml

    empty_asset_package:
        class: Symfony\Component\Asset\PathPackage
        arguments:
            $basePath: '/'
            $versionStrategy: '@assets.empty_version_strategy'
            $context: '@assets.context'

    asset_mapper.asset_package:
      class: Symfony\Component\AssetMapper\MapperAwareAssetPackage
      arguments:
        $innerPackage: '@empty_asset_package'
        $assetMapper: '@asset_mapper'

Then hack the ImportMapRenderer code:

--- a/symfony/asset-mapper/ImportMap/ImportMapRenderer.php 2025-09-25 18:32:54.228964800 -0500
+++ b/symfony/asset-mapper/ImportMap/ImportMapRenderer.php        2025-09-25 18:32:44.978752900 -0500
@@ -55,7 +55,7 @@
 
             if ($this->assetPackages) {
                 // ltrim so the subdirectory (if needed) can be prepended
-                $path = $this->assetPackages->getUrl(ltrim($path, '/'));
+                $path = $this->assetPackages->getUrl(ltrim($path, '/'), 'asset_mapper.asset_package');
             }
 
             // if this represents the polyfill, hide it from the import map
@@ -66,7 +66,7 @@
 
             // for subdirectories or CDNs, the import name needs to be the full URL
             if (str_starts_with($importName, '/') && $this->assetPackages) {
-                $importName = $this->assetPackages->getUrl(ltrim($importName, '/'));
+                $importName = $this->assetPackages->getUrl(ltrim($importName, '/'), 'asset_mapper.asset_package');
             }
 
             $preload = $data['preload'] ?? false;

The basic idea behind this solution is to create a MapperAwareAssetPackage that uses the EmptyVersionStrategy. Then force the renderer to use this asset package by name, so it doesn't conflict with the default one. Maybe an official patch can follow the same idea. Any other ideas welcomed.