Import maps

[![npm][npm]][npm-url]
[![download][download]][download-url]
[![size][size]][size-url]

[npm]: https://img.shields.io/npm/v/import-maps.svg
[npm-url]: https://npmjs.com/package/import-maps
[download]: https://img.shields.io/npm/dm/import-maps.svg?style=flat
[download-url]: https://npmcharts.com/compare/import-maps?minimal=true
[size]: https://packagephobia.now.sh/badge?p=import-maps
[size-url]: https://packagephobia.now.sh/result?p=import-maps

Reference implementation playground for import maps proposal.

Copy from WICG's import-maps implementation.

Install

Using npm:

``sh
npm install import-maps
`

or using yarn:

`sh
yarn add import-maps
`

Usage

The import-maps files:

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

$3

`js
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);
}
`

$3

`ts
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:

`json
{
"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.