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.