systemjs/docs/import-maps.md

Import Maps

Import maps are the current specification for mapping bare specifier names in the browser.

This means module specifiers like "lodash" can be mapped to exact URLs for loading.

Note the import maps specification is still under active development and as such this implementation will be subject to change.

Loading Import Maps

Import maps can be loaded inline or from a separate URL using a <script type="systemjs-importmap"> tag:

<!-- Separate src: -->
<script type="systemjs-importmap" src="/path/to/importmap.json">

<!-- Inline: -->
<script type="systemjs-importmap">
{
  "imports": {
    "lodash": "/path/to/lodash/index.js",
    "lodash/": "/path/to/lodash/"
  },
  "scopes": {
    "/path/to/lodash/": {
      "lodash-dependency": "/path/to/scoped/package.js"
    }
  }
}
</script>

The import map is fixed as soon as the first System.resolve (or indirectly through System.import) is called. At this point no new import maps can be loaded currently, although this is under specification discussion at https://github.com/WICG/import-maps/issues/92.

Imports

For base-level specifier mappings, we can use the "imports" property:

<script type="systemjs-importmap">
{
  "imports": {
    "lodash": "/path/to/lodash/index.js"
  }
}
</script>

The above will resolve any import 'lodash' call to the path we have provided.

For submodules, loading import 'lodash/x' will not be supported in the above.

To more clearly define package folders we can use package folder mappings:

<script type="systemjs-importmap">
{
  "imports": {
    "lodash": "/path/to/lodash/index.js",
    "lodash/": "/path/to/lodash/"
  }
}
</script>

In this scenario import 'lodash' will resolve to /path/to/lodash/index.js while import 'lodash/x' will resolve to /path/to/lodash/x.

Scopes

Import maps also provide support for scoped mappings, where the mapping should only be applied within a specific base path.

For example, say that we want lodash to resolve to one version in /app and that /lib/x should resolve a different version of lodash.

This can be achieved with scoped import maps:

<script type="systemjs-importmap">
{
  "scopes": {
    "/app/": {
      "lodash": "/path/to/lodash@2.0.0.js"
    },
    "/lib/x/": {
      "lodash": "/path/to/lodash@1.0.0.js"
    }
  }
}
</script>

Scopes still fallback to applying the global imports, so we only need to do this for imports that are different from their global resolutions.

Spec and Implementation Feedback

Part of the benefit of giving users a working version of an early spec is being able to get real user feedback on the spec.

If you have suggestions, or notice cases where this implementation seems not to be following the spec properly feel free to post an issue.

The edge cases are still being worked out, so there will still be work to do here too.

Read the full specification for the exact behaviours further.