Add an API for importmaps

I love this idea, and think an addition to the libraries.yml would be the perfect place to declare es module usage. For example from the react module's current usage of the importmaps module:

react.libraries.yml

react:
  js:
    'js/dist/react.js': { minified: true }

react-dom:
  js:
    'js/dist/react-dom.js': { minified: true }
  dependencies:
    - react/react

react.importmaps.yml

react:
  path: js/dist/react.js
react-dom:
  path: js/dist/react-dom.js
react/jsx-runtime:
  path: js/dist/react-jsx-runtime.js

To kick off some discussion here, re-imagining this as a single .libraries.yml file could become one of several options, each with their own benefits/drawbacks.

Option 1: Adding importpath info to a JS asset

react:
  js:
    'js/dist/react.js': { minified: true, esmodule: 'react' }

react-dom:
  js:
    'js/dist/react-dom.js': { minified: true, esmodule: 'react-dom' }
  dependencies:
    - react/react

Pros:

• Minimal addition to the yaml structure
• Tight coupling to current libraries

Cons:

• JS files don't necessarily need to be loaded on a page for the import map to work, but this approach would add them into the DOM 100% of the time

Option 2: Adding importpath info to an individual library

react:
  js:
    'js/dist/react.js': { minified: true }
  imports:
    'react': 'js/dist/react.js' 

react-dom:
  js:
    'js/dist/react-dom.js': { minified: true }
  imports:
    'react-dom': 'js/dist/react-dom.js'
  dependencies:
    - react/react

Pros:

• Moderate coupling to current libraries
• Files that exist only as "sources" of modules won't get unnecessarily loaded to the page

Cons:

• Files that both need to both run *and* operate at a module's source have to be duplicated

Option 3: Adding importpath info as a separate non-library top level item

react:
  js:
    'js/dist/react.js': { minified: true }

react-dom:
  js:
    'js/dist/react-dom.js': { minified: true }
  dependencies:
    - react/react

IMPORT_PATH:
  'react': 'js/dist/react.js'
  'react-dom': 'js/dist/react-dom.js'

Pros:

• Offers the greatest flexibility

Cons:

• Loosest coupling to libraries
• Requires a "magic" library name

I think your option 4 is the same as my option 2, though?

Symfony's AssetMapper component provides support for importmaps, it doesn't look like we can fully leverage this component directly, but we could learn from it and perhaps use some of their code.

https://symfony.com/doc/current/frontend/asset_mapper.html

I started a POC contrib module that implements this: https://www.drupal.org/project/importmap

It uses data attributes to avoid breaking the libraries.yml YAML schema. But if core implemented this, it could of course be with new properties in the YAML.

in classic drupal fashion we're jumping the gun to implementation before getting the scope cleared up :)

I'm leaning towards option 2 with the "importmap" key to match what it's called in html.

That's why I'm very satisfied we have peast in core now, we can actually look into the js files and extract stuff. Ideally I'd like to dynamically build the dependencies from what's declared in the js file itself to avoid having to double-declare dependencies.

Closed #3331393: Provide management/mechanism for JS/ES6 importmap since this one has more activity and a better issue summary.

Hmm, thanks, but feels odd to create a competing module one week after I made one at drupal.org/project/importmaps - we should be collaborating (I mentioned it in comment 4)

Sorry, I did not see your module. I was initially following the duplicate issue and not this one.
I created an issue about merging the two modules: #3399978: Merge with importmap module

in classic drupal fashion we're jumping the gun to implementation before getting the scope cleared up :)

We had a concrete need for this and thought it would be better to publish it as a contrib module, to get ideas rolling.
But I agree that we need to think about the best way to declare imports before adding this to core.

My initial thought was that it would make sense to have this in the library definitions since these are in fact libraries. But I agree that we would almost never need to load a JS file both as an import and with a script tag, so I guess it can make sense to a have a separate top-level key (or even a separate YAML file) for this.

We also might want to support scopes.

That's why I'm very satisfied we have peast in core now, we can actually look into the js files and extract stuff. Ideally I'd like to dynamically build the dependencies from what's declared in the js file itself to avoid having to double-declare dependencies.

I don't think this would work with dynamic imports.

But I am not entirely sure we have to care about dependencies here.
Having a module in the import map has no effect if it is not imported by some other JS module. So we could always include every declared module in the import map and don't bother managing dependencies.

It is only tangentially related but there is also #3366561: Support preloading of fonts in the libraries API where the main barrier is figuring out the definition format.

Regardless of the format, anything marked for import needs to be completely excluded from Drupal's asset rendering (and aggregation if it's enabled). Drupal just should not be loading it at all; instead just providing the markup so it can be loaded on demand via the browser.

A top-level entry in libraries would not hurt here, because it then wouldn't be possible to mix imported vs. not scripts in a single library definition.

Can we be certain that we won't get a mix of libraries relying on importmaps vs. libraries relying on library dependencies? That seems like it would not be good.

An issue with taking these files out of the asset rendering system is that they won't get the asset query string or any version information etc. appended unless we handle that too - so maybe we would need to re-implement/re-use at least that bit for cache busting.

If we hit some limits of the import map api, An alternative solution could be reaching into the js source and rewrite import paths at process/bundle time.

I'm worried that the import map will end up being massive for something like Drupal. Maybe not, we'll see when we get there I guess.

Do we need to worry about security if we have an import map with everything? I know we don't have access rules on js assets by design so it shouldn't be an issue but you never know.

Symfony has a FAQ page that points to this example: https://ux.symfony.com/
It is a production website with ~100 files in the import map.

Anybody still working on this? Maybe during Barcelona?

The change record branch and version info needs to be updated as well as the text which refers to 10.3. Should the change record introduce the new api?

Really excited about this feature!

Would probably outside of the scope of this issue if there is any follow up, but after reviewing the in-progress implementation it got me thinking about how this would apply to single directory components.

My best guess is that you'd currently have to:

* In the component.yml for the SDC itself, override the library to add the module attribute for the js asset:

  js:
    my-component.js: { attributes: { module: true } }

* Add an importmap.yml file at the root of the module or theme that defines the single directory component. In that file you'd need to reference the library by the name auto-generated by sdc (core/components.[THEME_OR_MODULE_NAME]--[COMPONENT_NAME_WITH_DASHES])

That would at least make adding js from a component to the import map possible on the current feature branch, which is great. But it feels like there could be some syntactic sugar in the sdc module to make this easier. One of the great things (imho) about SDCs is that a developer can write a js file and not worry about defining a library. Would love to see that concept extend to import maps.

It seems like the `hook_importmap_alter` added here would make it pretty straightforward to implement this in the sdc module once it is determined what could be used to communicate that js should be included in an import map / handled as a module.

Thoughts?

There's been some discussion on asset bundling, importmap, and SDC in the Frontend Builder Initiative slack channel.

@brianperry can you elaborate a little more on the use case (In slack if not here)? I hit some things that might be relevant, but I'm not totally sure.

One example is a SDC that imports a js module from npm, like swiper. If a module uses it as a library, and my theme component bundles it, is there some way put the bundled version in the importmap and override the module using the library? I'm not sure if this even makes sense though, or if it just makes more sense to set up front end bundling in the root and override the module to use your library.

There's some overlap in manifest.json files for bundled assets and importmaps. I'm not sure if there's any benefit to using a global importmap vs individually bundled or even globally bundled assets.

Another issue is referencing images or icons in the theme directory. When I bundle in the theme dir, the paths are relative to the theme root and drupal uses the Vite module to translate them to the correct path. Since we don't have libraries defined for images, there's some extra config needed to juggle the paths that I haven't figured out yet. I'm not sure if images in the importmap are possible or would just cause more problems.

> The importmap functionality is really only when you have unknown consumers. E.g. React module doesn't know what themes/modules will need to load react.

I get that this is the primary use case driving this issue, but I don't know that I agree with this statement broadly. Import maps also simplify the process of using esmodule imports in unbundled code. It would be possible for example to create a small utility in a vanilla js file that is exported as a module, which could then be imported in other js module files where needed. You don't necessarily need import maps to do that, but Drupal's library system / asset handling can make it tricky to negotiate module paths without something like an import map.

In practice most complex projects will use a bundler, but this pure esm approach seems like something that could grow over time.

Symfony's Asset Mapper component uses import maps extensively. In fact, they seem to recommend asset mapper as a default

Elsewhere in the FE ecosystem the Islands Architecture popularized by Astro is built on top of esm imports. Their `client:*` directives result in a custom element that loads the necessary javascript via a dynamic import.

While this issue sparked questions related to SDCs since I have been working with them lately, I'm also following this because I've been experimenting with a Drupal Islands Architecture implementation. Based on experiments thus far, I think a Drupal import map implementation would be needed to make this viable. The current POC builds its own import map. It isn't really packaged up for easy consumption at the moment, but I'll try to follow up here when that changes.

> @brianperry can you elaborate a little more on the use case (In slack if not here)? I hit some things that might be relevant, but I'm not totally sure.

@mortona2k I'll say hi in the slack channel, but I'm mostly thinking about the un-bundled use case above.

Just in case this is in any way helpful:
Geolocation module v4 moved to almost complete ES6 modules. A lot of them. And for lack of importmap support its all handled by dynamic imports. And they spread out over 10 sub-modules.

So, this is already out there and I would be more than happy to move away from keeping track of all the relative paths and to an importmap mechanism provided by core.

The Needs Review Queue Bot tested this issue. It no longer applies to Drupal core. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

However, you can only have one <script type="importmap"> element on a page, so therefore it makes sense to have an API in core to support this. In addition you cannot dynamically update this, so e.g. things like Ajax responses cannot add new importmaps. As a result we need to declare all possible import maps on the page.

A couple months ago, Multiple import maps was merged into the HTML spec. Chrome will support this in v133. TBD when other browsers will catch up.

• Webkit merged it Jan 2, 2025: https://bugs.webkit.org/show_bug.cgi?id=279025
• Firefox only has an issue open: https://github.com/mdn/mdn/issues/622

@larowlan how would #37 work with big pipe and AJAX?

multiple importmap scripts is coming to browsers which would also help, but that's a way off yet

I don't think it's that far off. It's in Chrome 133 and Safari HEAD (Tech Preview). https://bugzilla.mozilla.org/show_bug.cgi?id=1916277 is the issue for Firefox, they're just choosing to block it on landing import map integrity verification first.

We won't be able to require multiple import maps until Firefox ESR supports it, but I think if we're only adding the API for contrib to use initially, we could assume multiple import map support and just not use it in core until it's available in ESR.

Not sure this was discussed yet: browser cache invalidation can be a challenge.
For files in the importmap, we can add a GET parameter (generated with AssetQueryString) to invalidate browser cache when the file changes:

"swiper": "\/themes\/custom\/front\/node_modules\/swiper\/swiper.mjs?sxoxj0"

However if this file then does another import with a relative path:

export {default as Virtual} from './virtual.mjs';

We have no way to invalidate browser cache when this other file changes.

Firefox still doesn't support multiple import maps:

https://caniuse.com/mdn-html_elements_script_type_importmap_multiple_imp...

It looks like it's being tracked in https://bugzilla.mozilla.org/show_bug.cgi?id=1916277

However per #41 I still think we should add support for multiple import maps, and delay usage of it until Firefox ESR has support.

There's a comment in that Mozilla issue that mentions https://github.com/guybedford/es-module-shims, a polyfill for multiple import maps (and other import map features) for browsers that don't support it natively.

Firefox still doesn't have support for multiple import maps, but the end of the year is getting closer and we will need this for any CKEditor release in 2026 for #3527914: Use UMD installation method for CKEditor5

Given that most other browsers do support multiple import maps I think we should go ahead and use the polyfill here.

Rebased against 11.x, the performance test changes were unmergeable and will need redoing, otherwise the only big change was the conversion of system_page_top() to OOP.

The core/tests/Drupal/Tests/Core/Test/TestDiscoveryTest.php is failing with below error:

❯ ddev phpunit core/tests/Drupal/Tests/Core/Test/TestDiscoveryTest.php
PHPUnit 11.5.22 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.3.23
Configuration: /var/www/html/ddev.phpunit.xml

.............................                                     29 / 29 (100%)

Time: 00:03.834, Memory: 66.00 MB

There was 1 PHPUnit test runner warning:

1) Test results may not be as expected because the XML configuration file did not pass validation:

  Line 22:
  - Element 'phpunit', attribute 'failOnPhpunitWarning': The attribute 'failOnPhpunitWarning' is not allowed.


OK, but there were issues!
Tests: 29, Assertions: 52, Warnings: 5, PHPUnit Deprecations: 1.
Failed to run phpunit core/tests/Drupal/Tests/Core/Test/TestDiscoveryTest.php: exit status 1

This is triggered by the 11.x change to enable the PHPUnit errors. mostly it means we need to make sure all the re-rolling MRs with new tests would face this issue.

Something else that was not discussed I think: importmaps might break with strict CSPs that don't allow unsafe-inline.
The import needs to be allowed with its hash or a nonce.

I tried to use import-maps today and experienced some incompatibility issues in Firefox. The Import-Map was defined after a script with type="module".

The error message was: "Import maps are not allowed after a module load or preload has started."

I think import-maps should move to HTML head. Maybe build it in hook_page_attachments?

Just double-checked firefox again and nothing has changed since #48 https://caniuse.com/mdn-html_elements_script_type_importmap_multiple_imp... so +1 to adding the polyfill.

Something to keep an eye on too: https://lea.verou.me/blog/2026/external-import-maps-today/ and the corresponding lib https://github.com/nudeps/nudeps

Tagging this as a D12 release priority.

Looks like multiple import maps will be supported in Firefox 150: https://bugzilla.mozilla.org/show_bug.cgi?id=1916277

This is scheduled for release in a month from now, but will initially be marked as experimental. We have to wait for Firefox ESR anyway, where hopefully it will be enabled by default, but no guarantees. The next ESR release is Firefox 153 which will be on 21 July 2026.

Looking at recent comments on that Firefox issue, it looks like even with 150, it might be considered experimental and gated behind an off-by-default preference flag. In which case, we'll still need the polyfill until Firefox releases the feature ungated.

[Edit: sorry, I see you mentioned that in #61 as well. I missed that when I first read that comment.]

https://bugzilla.mozilla.org/show_bug.cgi?id=2021012 is the new Firefox ticket for enabling it by default.

Now that #3527914: Use UMD installation method for CKEditor5 went in without this, I don't think it's critical, but it would still be good to support, so moving to 'major'.