Import maps

Reference implementation playground for import maps proposal.

Copy from WICG's import-maps implementation.

Install

Using npm:

npm install import-maps

or using yarn:

yarn add import-maps

Usage

The import-maps files:

{
  "imports": {
    "a": "/1",
    "a/": "/2/",
    "a/b": "/3",
    "a/b/": "/4/"
  }
}

JavaScript

import { resolve, parseFromString } from "import-maps";
 
const importMapBaseURL = "https://example.com/app/index.html";
const scriptBaseURL = "https://example.com/js/app.mjs";
const rawImportMaps = `{
  "imports": {
    "a": "/1",
    "a/": "/2/",
    "a/b": "/3",
    "a/b/": "/4/"
  }
}`;
 
try {
  const parsedImportMaps = parseFromString(rawImportMaps, importMapBaseURL);
  const parsedUrl = resolve('a', parsedImportMaps, new URL(scriptBaseURL));
  console.log(parsedUrl);
  // URL {
  //   href: 'https://example.com/1',
  //   origin: 'https://example.com',
  //   protocol: 'https:',
  //   username: '',
  //   password: '',
  //   host: 'example.com',
  //   hostname: 'example.com',
  //   port: '',
  //   pathname: '/1',
  //   search: '',
  //   searchParams: URLSearchParams {},
  //   hash: ''
  // }
  } catch (e) {
  console.trace(e);
}

TypeScript

import { resolve, parseFromString, ImportMaps } from "import-maps";
 
const rawImportMaps: string = `{
  "imports": {
    "a": "/1",
    "a/": "/2/",
    "a/b": "/3",
    "a/b/": "/4/"
  }
}`;
 
const importMapBaseURL: string = "https://example.com/app/index.html";
const scriptBaseURL: string = "https://example.com/js/app.mjs";
 
try {
  const parsedImportMaps: ImportMaps = parseFromString(rawImportMaps, importMapBaseURL);
  const parsedUrl: URL = resolve('a', parsedImportMaps, new URL(scriptBaseURL));
  console.log(parsedUrl);
  // URL {
  //   href: 'https://example.com/1',
  //   origin: 'https://example.com',
  //   protocol: 'https:',
  //   username: '',
  //   password: '',
  //   host: 'example.com',
  //   hostname: 'example.com',
  //   port: '',
  //   pathname: '/1',
  //   search: '',
  //   searchParams: URLSearchParams {},
  //   hash: ''
  // }
} catch (e) {
  console.trace(e);
}

Note ⚠️

The return value of resolve is a URL instead of a string.

Scope inheritance

Scopes "inherit" from each other in an intentionally-simple manner, merging but overriding as they go. For example, the following import map:

{
  "imports": {
    "a": "/a-1.mjs",
    "b": "/b-1.mjs",
    "c": "/c-1.mjs"
  },
  "scopes": {
    "/scope2/": {
      "a": "/a-2.mjs"
    },
    "/scope2/scope3/": {
      "b": "/b-3.mjs"
    }
  }
}

would give the following resolutions:

Specifier	Referrer	Resulting URL
a	/scope1/foo.mjs	/a-1.mjs
b	/scope1/foo.mjs	/b-1.mjs
c	/scope1/foo.mjs	/c-1.mjs
a	/scope2/foo.mjs	/a-2.mjs
b	/scope2/foo.mjs	/b-1.mjs
c	/scope2/foo.mjs	/c-1.mjs
a	/scope2/scope3/foo.mjs	/a-2.mjs
b	/scope2/scope3/foo.mjs	/b-3.mjs
c	/scope2/scope3/foo.mjs	/c-1.mjs

License

All Reports in this Repository are licensed by Contributors under the W3C Software and Document License.

Contributions to Specifications are made under the W3C CLA.