README

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.

Usage no npm install needed!