Intent to Implement: Import maps, basic support

[Hiroshige Hayashizaki]

Contact emails

hiro...@chromium.org, dom...@chromium.org, kou...@chromium.org

Explainer

https://github.com/WICG/import-maps

Design doc/Spec

A full spec is still under development, and will be informed by this work. In addition to the explainer, the following documents are providing guidance to our implementation:

• Proto-spec, including more detailed semantics for acquiring import maps

• Early spec draft, which mostly delegates to a JavaScript reference implementation of parsing and module resolution.

We also have an implementation design doc.

We've filed a TAG review request.

Summary

Import maps allows control over what URLs get fetched by JavaScript import statements and import() expressions.

This intent only covers a subset of import maps features:

• Fallback only from built-in modules.

• Basic support to map bare specifier to actual URLs.

• Scoping of the mapping.

applied to module script specifiers that appear in:

• import statements in module scripts, and

• dynamic import() in (module or classic) scripts.

And does NOT include the following:

• Fallback involving non-builtin modules (e.g. fallback from HTTPS to another HTTPS URL)

• Use of import: URLs

• <script> elements' src attribute (even when type="module")

• Other non-script contexts, like workers

(This roughly corresponds to cover the first two or three items and to intentionally exclude the last item in the implementation staging in the WICG explainer.)

Motivation

Import maps enable built-in modules. So far we have avoided speccing and shipping any built-in modules, in large part because they have disadvantages compared to built-in globals. Import maps is an attempt to address these disadvantages.

Concretely, while globals can be polyfilled or virtualized, without import maps, modules cannot be. See more examples in the explainer, for polyfills and for virtualization. Without import maps, the web will likely continue to need to expose features through global variables forever.

Import maps fill the gap between the web platform and other JS modules implementations by allowing the mapping of bare specifiers (e.g. import $ from "jquery"). Web developers used to Node.js, webpack, TypeScript, or other environments expect this capability, but until import maps the web platform would always throw an exception for such imports. Without import maps, developers are generally forced to transpile, i.e. not use the native module system. More background and examples in the explainer.

Risks

Interoperability and Compatibility

Interoperability risks:

The overall structure of full import maps spec is not yet converged due to ongoing spec discussions (e.g. #18, #76, #79).

This Intent tries to take and implement a subset that is not directly affected by the ongoing spec issues, but the structure of the implementation will be different from the structure of the current proposed spec, which causes some minor behavior differences from the current proposed spec.

See Diffs from Full Import Maps Spec Proposal section for details.

In general, we have found other vendors to be positive and collaborative on this approach, as seen in an (unfortunately unminuted) TPAC 2018 session, collaboration at TC39 including with Apple's JavaScript standard library proposal, and work with Mozilla on how this integrates with WebAssembly. We do not have any publicly linkable statements at this time that would qualify as "Public support", however.

Web and framework developers have been generally positive, including extensive contributions and pull requests to the spec, a polyfill, and an import maps generator created by a maintainer of the Yarn JavaScript package manager. They are especially excited about solving the long-standing feature request of bare specifier support.

Compatibility risks:

None, because this proposal doesn't change existing web pages without import maps. Indeed, it provides a mechanism for polyfilling effectively, i.e. improving compatibility.

Ergonomics
This API will be used in tandem with the JavaScript module system in general, and with built-in modules in particular. A lot of attention has been paid to making the mapping relatively easy to use and ergonomic.

This API should help Chrome maintain good performance, as part of a larger program to encourage the use of more granular modules (which can be performance-advantageous over large blocks of bundled script), and also to enable built-in modules, which can be loaded lazily instead of bloating each context.

Activation
This feature is specifically designed to improve the activation of built-in modules, allowing web developers to take advantage of them even in browsers without import maps or built-in module support. (See example.)

For the non built-in module use cases, polyfills like the excellent es-module-shims will definitely be helpful.

Additionally, tooling like the various bundlers or package managers will likely want to interact with import maps, either consuming or outputting them. We will be doing outreach during the implementation, once they have something they are able to test behind a flag.

Debuggability

One concern that has been raised during specification development is ensuring that warnings get triggered for various problems with the map (spec issue #80). We will be working to specify and implement such warnings.

Also, full logging information for each import map resolution will be helpful, for example:

• Showing how import maps are parsed (by printing the normalized, parsed import map data structure, to detect whether the provided string is parsed as expected).

• Which key of the import map is used (to debug the matching of import map keys).

• Which value of the import map is used (e.g. why the fallback occurred or didn't occur).

We still need to explore how to expose this, and will work with the DevTools team to figure that out.

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?

Yes.

Is this feature fully tested by web-platform-tests?

Yes.

Planning to add WPT tests, as well as importing and adapting tests from the reference implementation:

https://github.com/WICG/import-maps/tree/master/reference-implementation/__tests__

Link to entry on the feature dashboard

https://www.chromestatus.com/features/5315286962012160

Requesting approval to ship?

No

[a...@google.com]

Is there an existing security review bug for this feature? Given that this proposal makes a non-trivial change to the web security model (it creates an OOB mechanism that can replace a script with a cross-origin resource), it seems like it could use a closer look -- the questionnaire answers in https://github.com/WICG/import-maps/blob/master/Security%20and%20Privacy.md are useful, but I think there is a little more to consider here. A full Security section in the spec would be nice :)

As one specific example of something to think about, in the code from the design doc:

<script type="importmap">

{"imports": {"https://example.com/foo.js": [ "https://example.org/bar.js" ]}}

</script>

How would this interact with script-src in CSP? I.e. would both URLs have to be allowed by the policy for the module to load?

Cheers,

-Artur

[Hiroshige Hayashizaki]

Hi,

Sorry for delay.

> Is there an existing security review bug for this feature?

Not yet. We started discussion.

> How would this interact with script-src in CSP?

Only the URL after mapping (https://example.org/bar.js) should be allowed by policy.

Thanks,

Hiroshige

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/e2e90777-914c-4038-9300-c891936a348a%40chromium.org.

[hqj...@gmail.com]

Here is transformation for babel that supports bare imports https://github.com/hqjs/babel-plugin-transform-name-imports

[Tzvetelin Vassilev]

Hi,

This is a great feature, long time expected. Main thread can benefit from it. What are the future plans for other threads? Is there development that will cover workers? For threaded web app this feature looks like half done job.

Thanks,

Tzvetelin Vassilev

[Domenic Denicola]

Hey Tzvetelin, thanks for chiming in. We currently don't have anyone working on worker support for import maps, but getting feedback like this is really helpful for knowing what developers are missing. We know that there are several desired features for import maps (external import maps, multiple import maps, worker import maps, SRI metadata, ...) and would love to spend more time on it based on developer feedback.

One thing you can do to help signal this support is add a thumbs-up to the original post in https://github.com/WICG/import-maps/issues/2 .

[Arthur Hemery]

Hi!
This showed up in the OWP Security&Privacy review queue and I noticed it was posted 2 years ago. Domenic do you know if this is still being worked on?
Thanks,
Arthur

[Domenic Denicola]

Yes, basic import maps support shipped two years ago.