Import Maps

Draft Community Group Report,

This version:
https://wicg.github.io/import-maps/
Editor:
Domenic Denicola (Google)
Participate:
GitHub WICG/import-maps (new issue, open issues)
Commits:
GitHub spec.bs commits
Not Ready For Implementation

This spec is not yet ready for implementation. It exists in this repository to record the ideas and promote discussion.

Before attempting to implement this spec, please contact the editors.

Copyright © 2021 the Contributors to the Import Maps Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

Abstract

Import maps allow web pages to control the behavior of JavaScript imports, and introduce a new import: URL scheme to allow using this mapping in other URL-accepting contexts

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Definitions

A specifier map is an ordered map from strings to lists of URLs.

A import map is a struct with two items:

An empty import map is an import map with its imports and scopes both being empty maps.

To update an import map importMap with a second import map newImportMap:

  1. For each specifier → addresses of newImportMap’s imports, set importMap’s imports[specifier] to addresses.

  2. For each url → specifierMap of newImportMap’s scopes, set importMap’s scopes[url] to specifierMap.

  3. Set importMap’s imports to the result of sorting importMap’s imports, with an entry a being less than an entry b if a’s key is longer or code unit less than b’s key.

  4. Set importMap’s scopes to the result of sorting importMap’s scopes, with an entry a being less than an entry b if a’s key is longer or code unit less than b’s key.

Update an import map merges the two import maps in a very simple way, not performing any deep merging beyond the top level of the "imports" and "scopes" keys. For example, 
<script type="importmap">
{
  "imports": {
    "a": "/a-1.mjs",
    "b": "/b-1.mjs",
    "std:kv-storage": ["std:kv-storage", "/kvs-1.mjs"]
  },
  "scopes": {
    "/scope1/": {
      "a": "/a-2.mjs"
    }
  }
}
</script>
<script type="importmap">
{
  "imports": {
    "b": null,
    "std:kv-storage": "kvs-2.mjs"
  },
  "scopes": {
    "/scope1/": {
      "b": "/b-2.mjs"
    }
  }
}
</script>

is equivalent to

<script type="importmap">
{
  "imports": {
    "a": "/a-1.mjs",
    "b": null,
    "std:kv-storage": "kvs-2.mjs"
  },
  "scopes": {
    "/scope1/": {
      "b": "/b-2.mjs"
    }
  }
}
</script>

Notice how the definition for "/scope1/" was completely overridden, so there is no longer a redirection for the "a" module specifier within that scope.

2. Acquiring import maps

2.1. New members of environment settings objects

Each environment settings object will get an import map algorithm, which returns an import map created by parsing and merging all <script type="importmap"> elements that are encountered (before the cutoff).

A Document has an import map import map. It is initially a new empty import map.

In set up a window environment settings object, settings object’s import map returns the import map of window’s associated Document.

A WorkerGlobalScope has an import map import map. It is initially a new empty import map.

Specify a way to set WorkerGlobalScope's import map. We might want to inherit parent context’s import maps, or provide APIs on WorkerGlobalScope, but we are not sure. Currently it is always an empty import map. See #2.

In set up a worker environment settings object, settings object’s import map returns worker global scope’s import map.

This infrastructure is very similar to the existing specification for module maps.

A Document has a list of pending import map scripts, which is a list of HTMLScriptElements, initially empty.

HTMLScriptElements are added to this list by § 2.3 Prepare a script.

Each Document has an acquiring import maps boolean. It is initially true.

These two pieces of state are used to achieve the following behavior:

2.2. Script type

To process import maps in the prepare a script algorithm consistently with existing script types (i.e. classic or module), we make the following changes:

The following algorithms are updated accordingly:

Because we don’t make import map parse result the new subclass of script, other script execution-related specs are left unaffected.

2.3. Prepare a script

Inside the prepare a script algorithm, we make the following changes:

CSP is applied to import maps just like JavaScript scripts. Is this sufficient? #105.

This is specified similar to the list of scripts that will execute in order as soon as possible, to register import maps and fire error events in order (list of scripts that will execute in order as soon as possible is rarely used in the wild though). There can be other alternatives, e.g. executing a similar loop inside wait for import maps.

To fetch an import map given url, settings object, and options, run the following steps. This algorithm asynchronously returns an import map or null.

This algorithm is specified consistently with fetch a single module script steps 5, 7, 8, 9, 10, and 12.1. Particularly, we enforce CORS to avoid leaking the import map contents that shouldn’t be accessed.

  1. Let request be a new request whose url is url, destination is "script", mode is "cors", referrer is "client", and client is settings object.

    Here we use "script" as the destination, which means the script-src-elem CSP directive applies.

  2. Set up the module script request given request and options.

  3. Fetch request. Return from this algorithm, and run the remaining steps as part of the fetch’s process response for the response response.

    response is always CORS-same-origin.

  4. If any of the following conditions are met, asynchronously complete this algorithm with null, and abort these steps:

  5. Let source text be the result of UTF-8 decoding response’s body.

  6. Asynchronously complete this algorithm with the result of create an import map parse result, given source text, response’s url, and settings object.

2.4. Wait for import maps

To wait for import maps given settings object:

  1. If settings object’s global object is a Window object:

    1. Let document be settings object’s global object's associated Document.

    2. Set document’s acquiring import maps to false.

    3. Spin the event loop until document’s list of pending import map scripts is empty.

  2. Asynchronously complete this algorithm.

No actions are specified for WorkerGlobalScope because for now there are no mechanisms for adding import maps to WorkerGlobalScope.

Insert a call to wait for import maps at the beginning of the following HTML spec concepts.

In this draft of the spec, which inserts itself into these HTML concepts, the settings object used here is the module map settings object, not fetch client settings object, because resolve a module specifier uses the import map of module map settings object. In a potential future version of the import maps infrastructure, which interjects itself at the layer of the Fetch spec in order to support import: URLs, we would instead use fetch client settings object.

This only affects fetch a module worker script graph, where these two settings objects are different. And, given that the import maps for WorkerGlobalScopes are currently always empty, the only fetch that could be impacted is that of the initial module. But even that would not be impacted, because that fetch is done using URLs, not specifiers. So this is not a future compatibility hazard, just something to keep in mind as we develop import maps in module workers.

Depending on the exact location of wait for import maps, import(unresolvableSpecifier) might behave differently between a HTML-spec- and Fetch-spec-based import maps. In particular, in the current draft, acquiring import maps is set to false after an import()-initiated failure to resolve a module specifier, thus causing any later-encountered import maps to cause an error event instead of being processed. Whereas, if wait for import maps was called as part of the Fetch spec, it’s possible it would be natural to specify things such that acquiring import maps remains true (as it does for cases like <script type="module" src="http://:invalidurl">).

This should not be much of a compatibility hazard, as it only makes esoteric error cases into successes. And we can always preserve the behavior as specced here if necessary, with some potential additional complexity.

2.5. Registering an import map

To register an import map given an HTMLScriptElement element:

  1. If element’s the script’s result is null, then fire an event named error at element, and return.

  2. Let import map parse result be element’s the script’s result.

  3. Assert: element’s the script’s type is "importmap".

  4. Assert: import map parse result is an import map parse result.

  5. Let settings object be import map parse result’s settings object.

  6. If element’s node document’s relevant settings object is not equal to settings object, then return.

    This is spec’ed consistently with whatwg/html#2673.

    Currently we don’t fire error events in this case. If we change the decision at whatwg/html#2673 to fire error events, then we should change this step accordingly.

  7. If import map parse result’s error to rethrow is not null, then:

    1. Report the exception given import map parse result’s error to rethrow.

      There are no relevant script, because import map parse result isn’t a script. This needs to wait for whatwg/html#958 before it is fixable.

    2. Return.

  8. Update element’s node document's import map with import map parse result’s import map.

  9. If element is from an external file, then fire an event named load at element.

The timing of register an import map is observable by possible error and load events, or by the fact that after register an import map an import map script can be moved to another Document. On the other hand, the updated import map is not observable until wait for import maps completes.

3. Parsing import maps

To parse an import map string, given a string input and a URL baseURL:

  1. Let parsed be the result of parsing JSON into Infra values given input.

  2. If parsed is not a map, then throw a TypeError indicating that the top-level value must be a JSON object.

  3. Let sortedAndNormalizedImports be an empty map.

  4. If parsed["imports"] exists, then:

    1. If parsed["imports"] is not a map, then throw a TypeError indicating that the "imports" top-level key must be a JSON object.

    2. Set sortedAndNormalizedImports to the result of sorting and normalizing a specifier map given parsed["imports"] and baseURL.

  5. Let sortedAndNormalizedScopes be an empty map.

  6. If parsed["scopes"] exists, then:

    1. If parsed["scopes"] is not a map, then throw a TypeError indicating that the "scopes" top-level key must be a JSON object.

    2. Set sortedAndNormalizedScopes to the result of sorting and normalizing scopes given parsed["scopes"] and baseURL.

  7. If parsed’s keys contains any items besides "imports" or "scopes", report a warning to the console that an invalid top-level key was present in the import map.

    This can help detect typos. It is not an error, because that would prevent any future extensions from being added backward-compatibly.

  8. Return the import map whose imports are sortedAndNormalizedImports and whose scopes scopes are sortedAndNormalizedScopes.

To create an import map parse result, given a string input, a URL baseURL, and an environment settings object settings object:

  1. Let import map be the result of parse an import map string given input and baseURL. If this throws an exception, let error to rethrow be the exception. Otherwise, let error to rethrow be null.

  2. Return an import map parse result with settings object is settings object, import map is import map, and error to rethrow is error to rethrow.

The import map is a highly normalized structure. For example, given a base URL of <https://example.com/base/page.html>, the input 
{
  "imports": {
    "/app/helper": "node_modules/helper/index.mjs",
    "std:kv-storage": [
      "std:kv-storage",
      "node_modules/kv-storage-polyfill/index.mjs",
    ]
  }
}

will generate an import map with imports of

«[
  "https://example.com/app/helper" → «
    <https://example.com/base/node_modules/helper/index.mjs>
  »,
  "std:kv-storage" → «
    <std:kv-storage>,
    <https://example.com/base/node_modules/kv-storage-polyfill/index.mjs>
  »
]»

and (despite nothing being present in the input) an empty map for its scopes.

To sort and normalize a specifier map, given a map originalMap and a URL baseURL:

  1. Let normalized be an empty map.

  2. First, normalize all entries so that their values are lists. For each specifierKey → value of originalMap,

    1. Let normalizedSpecifierKey be the result of normalizing a specifier key given specifierKey and baseURL.

    2. If normalizedSpecifierKey is null, then continue.

    3. If value is a string, then set normalized[normalizedSpecifierKey] to «value».

    4. Otherwise, if value is null, then set normalized[normalizedSpecifierKey] to a new empty list.

    5. Otherwise, if value is a list, then set normalized[normalizedSpecifierKey] to value.

    6. Otherwise, report a warning to the console that addresses must be strings, arrays, or null.

  3. Next, normalize and validate each potential address in the value lists. For each specifierKey → potentialAddresses of normalized,

    1. Assert: potentialAddresses is a list, because of the previous normalization pass.

    2. Let validNormalizedAddresses be an empty list.

    3. For each potentialAddress of potentialAddresses,

      1. If potentialAddress is not a string, then:

        1. Report a warning to the console that the contents of address arrays must be strings.

        2. Continue.

      2. Let addressURL be the result of parsing a URL-like import specifier given potentialAddress and baseURL.

      3. If addressURL is null, then:

        1. Report a warning to the console that the address was invalid.

        2. Continue.

      4. If specifierKey ends with U+002F (/), and the serialization of addressURL does not end with U+002F (/), then:

        1. Report a warning to the console that an invalid address was given for the specifier key specifierKey; since specifierKey ended in a slash, so must the address.

        2. Continue.

      5. If specifierKey’s scheme is "std" and the serialization of addressURL contains U+002F (/), then:

        1. Report a warning to the console that built-in module URLs must not contain slashes.

        2. Continue.

      6. Append addressURL to validNormalizedAddresses.

    4. Set normalized[specifierKey] to validNormalizedAddresses.

  4. Return the result of sorting normalized, with an entry a being less than an entry b if a’s key is longer or code unit less than b’s key.

To sort and normalize scopes, given a map originalMap and a URL baseURL:

  1. Let normalized be an empty map.

  2. For each scopePrefix → potentialSpecifierMap of originalMap,

    1. If potentialSpecifierMap is not a map, then throw a TypeError indicating that the value of the scope with prefix scopePrefix must be a JSON object.

    2. Let scopePrefixURL be the result of parsing scopePrefix with baseURL as the base URL.

    3. If scopePrefixURL is failure, then:

      1. Report a warning to the console that the scope prefix URL was not parseable.

      2. Continue.

    4. If scopePrefixURL’s scheme is not a fetch scheme, then:

      1. Report a warning to the console that scope prefix URLs must have a fetch scheme.

      2. Continue.

    5. Let normalizedScopePrefix be the serialization of scopePrefixURL.

    6. Set normalized[normalizedScopePrefix] to the result of sorting and normalizing a specifier map given potentialSpecifierMap and baseURL.

  3. Return the result of sorting normalized, with an entry a being less than an entry b if a’s key is longer or code unit less than b’s key.

To normalize a specifier key, given a string specifierKey and a URL baseURL:

  1. If specifierKey is the empty string, then:

    1. Report a warning to the console that specifier keys cannot be the empty string.

    2. Return null.

  2. Let url be the result of parsing a URL-like import specifier, given specifierKey and baseURL.

  3. If url is not null, then:

    1. Let urlString be the serialization of url.

    2. If url’s scheme is "std" and urlString contains U+002F (/), then:

      1. Report a warning to the console that built-in module specifiers must not contain slashes.

      2. Return null.

    3. Return urlString.

  4. Return specifierKey.

To parse a URL-like import specifier, given a string specifier and a URL baseURL:

  1. If specifier starts with "/", "./", or "../", then:

    1. Let url be the result of parsing specifier with baseURL as the base URL.

    2. If url is failure, then return null.

      One way this could happen is if specifier is "../foo" and baseURL is a data: URL.

    3. Return url.

  2. Let url be the result of parsing specifier (with no base URL).

  3. If url is failure, then return null.

  4. If url’s scheme is either a fetch scheme or "std", then return url.

  5. Return null.

A string a is longer or code unit less than b if a’s length is greater than b’s length, or if a is code unit less than b.

4. Resolving module specifiers

4.1. New "resolve a module specifier"

HTML already has a resolve a module specifier algorithm. We replace it with the following resolve a module specifier algorithm, given a script referringScript and a JavaScript string specifier:

  1. Let settingsObject be the current settings object.

  2. Let baseURL be settingsObject’s API base URL.

  3. If referringScript is not null, then:

    1. Set settingsObject to referringScript’s settings object.

    2. Set baseURL to referringScript’s base URL.

  4. Let importMap be settingsObject’s import map.

  5. Let moduleMap be settingsObject’s module map.

  6. Let baseURLString be baseURL, serialized.

  7. Let asURL be the result of parsing a URL-like import specifier given specifier and baseURL.

  8. Let normalizedSpecifier be the serialization of asURL, if asURL is non-null; otherwise, specifier.

  9. For each scopePrefix → scopeImports of importMap’s scopes,

    1. If scopePrefix is baseURLString, or if scopePrefix ends with U+002F (/) and baseURLString starts with scopePrefix, then:

      1. Let scopeImportsMatch be the result of resolving an imports match given normalizedSpecifier, scopeImports, and moduleMap.

      2. If scopeImportsMatch is not null, then:

        1. Validate the module script URL given scopeImportsMatch, settingsObject, and baseURL.

        2. Return scopeImportsMatch.

  10. Let topLevelImportsMatch be the reuslt of resolving an imports match given normalizedSpecifier, importMap’s imports, and moduleMap.

  11. If topLevelImportsMatch is not null, then:

    1. Validate the module script URL given topLevelImportsMatch, settingsObject, and baseURL.

    2. Return topLevelImportsMatch.

  12. At this point, the specifier was able to be turned in to a URL, but it wasn’t remapped to anything by importMap.

    If asURL is not null, then:

    1. Validate the module script URL given asURL, settingsObject, and baseURL.

    2. Return asURL.

  13. Throw a TypeError indicating that specifier was a bare specifier, but was not remapped to anything by importMap.

It seems possible that the return type could end up being a list of URLs, not just a single URL, to support HTTPS → HTTPS fallback. But, we haven’t gotten that far yet; for now let’s assume it stays a single URL.

To resolve an imports match, given a string normalizedSpecifier, a specifier map specifierMap, and a module map moduleMap:

  1. For each specifierKey → addresses of specifierMap,

    1. If specifierKey is normalizedSpecifier, then:

      1. If addresses’s size is 0, then throw a TypeError indicating that normalizedSpecifier was mapped to no addresses.

      2. If addresses’s size is 1, then:

        1. Let singleAddress be addresses[0].

        2. If singleAddress’s scheme is "std", and moduleMap[singleAddress] does not exist, then throw a TypeError indicating that the requested built-in module is not implemented.

        3. Return singleAddress.

      3. If addresses’s size is 2, and addresses[0]'s scheme is "std", and addresses[1]'s scheme is not "std", then:

        1. Return addresses[0], if moduleMap[addresses[0]] exists; otherwise, return addresses[1].

      4. Otherwise, we have no specification for more complicated fallbacks yet; throw a TypeError indicating this is not yet supported.

    2. If specifierKey ends with U+002F (/) and normalizedSpecifier starts with specifierKey, then:

      1. If addresses’s size is 0, then throw a TypeError indicating that normalizedSpecifier was mapped to no addresses.

      2. If addresses’s size is 1, then:

        1. Let afterPrefix be the portion of normalizedSpecifier after the initial specifierKey prefix.

        2. Let url be the result of parsing afterPrefix relative to addresses[0].

        3. If url is failure, throw a TypeError, implicating normalizedSpecifier (and in particular the afterPrefix portion).

        4. Return url.

      3. Otherwise, we have no specification for more complicated fallbacks yet; throw a TypeError indicating this is not yet supported.

  2. Return null.

To validate a module script URL, given a URL url, an environment settings object settings object, and a URL base URL:

  1. If url’s scheme is "std", then:

    1. If the serialization of url contains U+002F (/), then throw a TypeError indicating that url is a malformed built-in URL.

    2. Let moduleMap be settings object’s module map.

    3. If moduleMap[url] does not exist, then throw a TypeError indicating that the requested built-in module is not implemented.

      This condition is added to ensure that moduleMap[url] does not exist for unimplemented built-ins. Without this condition, fetch a single module script might be called and moduleMap[url] can be set to null, which might complicates the spec around built-ins.

    4. Return.

  2. If url’s scheme is not a fetch scheme, then throw a TypeError indicating that url is not a fetch scheme.

This algorithm provides a convenient place for implementations to insert other useful behaviors, as long as they are not observable to web content. For example, Chromium might insert the following step at the beginning of the algorithm:

  1. If url’s scheme is "std-internal" and base URL’s scheme is "std-internal", then return.

This introduces a type of internal built-in module that is only accessible to other internal built-in modules. Similar steps could be used to, for example, change how extension scripts access modules.

Since validate a module script URL is called before any module script fetches, such checks are reliable and can be used as a security mechanism.

4.2. Updates to other algorithms

All call sites of HTML’s existing resolve a module specifier will need to be updated to pass the appropriate script, not just its base URL. Some particular interesting cases:

Call sites will also need to be updated to account for resolve a module specifier now throwing exceptions, instead of returning failure. (Previously most call sites just turned failures into TypeErrors manually, so this is straightforward.)

In addition to the call sites for validate a module script URL explicitly added within this spec, insert the following at the beginning of fetch a single module script:

  1. Validate the module script URL given url, module map settings object, and module map settings object’s API base URL. If this throws an error, then asynchronously complete this algorithm with null, and abort these steps.

This will call validate the module script URL twice for each non-toplevel script fetch, first in resolve a module specifier, and then in fetch a single module script. The behavior of the two calls is identical.

Alternatively, we can add the snippet at the beginning of the following HTML spec concepts (after wait for import maps), so that the validation is not done twice:

Validate a module script URL is applied to all module URLs before they start loading, even in paths where resolve a module specifier and import maps are not applied (e.g. <script src="..." type="module">).

Appendix A: MIME type registration

This appendix provides the provisional registration of the MIME type application/importmap+json application/importmap+json in accordance with [RFC6838].

Type name:

application

Subtype name:

importmap+json

Required parameters:

N/A

Optional parameters:

N/A

Encoding considerations:

8bit (always UTF-8)

Security considerations:

Since Import Maps have the ability to direct which module resolutions are to be provided to all module imports of a given JavaScript environment, control of the Import Map should be considered to be execution-level application access. Integration with existing policy systems, including for example CORS and CSP, can be used to mitigate and restrict unwanted target URLs from being executed. In addition, the specification states that only those Import Maps served to browsers with the application/importmap+json MIME type will be executed. [FETCH] [CSP]

Interoperability considerations:

Backwards compatibility will be a necessity for any new features added to the format, and handling for this has been incorporated into the design of the specification.

Published specification:

https://wicg.github.io/import-maps/

Applications that use this media type:

This is a browser-specific MIME type but may also apply to other JavaScript environments.

Fragment identifier considerations:

N/A

Additional information:
Deprecated alias names for this type:

N/A

Magic number(s)

N/A

File extension(s):

"importmap"

Macintosh file type code:

Same as for application/json [JSON]

Person & email address to contact for further information:

Guy Bedford <guybedford@gmail.com>.

Intended usage:

Common

Restrictions on usage:

No restrictions apply.

Change controller:

WHATWG

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CONSOLE]
Dominic Farolino; Robert Kowalski; Terin Stock. Console Standard. Living Standard. URL: https://console.spec.whatwg.org/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[ENCODING]
Anne van Kesteren. Encoding Standard. Living Standard. URL: https://encoding.spec.whatwg.org/
[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[MIMESNIFF]
Gordon P. Hemsley. MIME Sniffing Standard. Living Standard. URL: https://mimesniff.spec.whatwg.org/
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
[WebIDL]
Boris Zbarsky. Web IDL. URL: https://heycam.github.io/webidl/

Informative References

[CSP]
Mike West. Content Security Policy Level 3. URL: https://w3c.github.io/webappsec-csp/
[JSON]
T. Bray, Ed.. The JavaScript Object Notation (JSON) Data Interchange Format. December 2017. Internet Standard. URL: https://tools.ietf.org/html/rfc8259
[RFC6838]
N. Freed; J. Klensin; T. Hansen. Media Type Specifications and Registration Procedures. January 2013. Best Current Practice. URL: https://tools.ietf.org/html/rfc6838

Issues Index

Specify a way to set WorkerGlobalScope's import map. We might want to inherit parent context’s import maps, or provide APIs on WorkerGlobalScope, but we are not sure. Currently it is always an empty import map. See #2. ↵
CSP is applied to import maps just like JavaScript scripts. Is this sufficient? #105. ↵
There are no relevant script, because import map parse result isn’t a script. This needs to wait for whatwg/html#958 before it is fixable. ↵