@jsenv/import-map

import-map

Helpers to implement importmaps.

Table of contents

• Presentation
• Installation
• composeTwoImportMaps
• normalizeImportMap
• resolveImport
• moveImportMap

Presentation

@jsenv/import-map can be used to implement the behaviour of importmap as described in the specification. It is written using es modules and compatible with browsers and Node.js. For instance, this repository is used to make ESLint compatible with importmaps.

• jsenv-importmap-eslint-resolver: ESLint plugin for importmaps
• import maps spec: WICG specs about import maps on GitHub

Installation

npm install @jsenv/import-map

composeTwoImportMaps

composeTwoImportMaps takes two importMap and return a single importMap being the composition of the two.

import { composeTwoImportMaps } from "@jsenv/import-map"

const importMap = composeTwoImportMaps(
  {
    imports: {
      foo: "bar",
    },
  },
  {
    imports: {
      foo: "whatever",
    },
  },
)

console.log(JSON.stringify(importMap, null, "  "))

{
  "imports": {
    "foo": "whatever"
  }
}

— source code at src/composeTwoImportMaps.js.

normalizeImportMap

normalizeImportMap returns an importMap resolved against an url and sorted.

import { normalizeImportMap } from "@jsenv/import-map"

const importMap = normalizeImportMap(
  {
    imports: {
      foo: "./bar",
      "./ding.js": "./dong.js"
    },
  },
  "http://your-domain.com",
)

console.log(JSON.stringify(importMap, null, '  ')

{
  "imports": {
    "foo": "http://your-domain.com/bar",
    "http://your-domain.com/ding.js": "http://your-domain.com/dong.js"
  }
}

— source code at src/normalizeImportMap.js.

resolveImport

resolveImport returns an import url applying an importMap to specifier and importer. The provided importMap must be resolved and sorted to work as expected. You can use normalizeImportMap to do that.

import { resolveImport } from "@jsenv/import-map"

const importUrl = resolveImport({
  specifier: "../index.js",
  importer: "http://domain.com/folder/file.js",
  importMap: {
    imports: {
      "http://domain.com/index.js": "http://domain.com/main.js",
    },
  },
})

console.log(importUrl)

http://domain.com/main.js

— source code at src/resolveImport.js.

moveImportMap

moveImportMap receives importMap, fromUrl, toUrl and return an importmap where all relative urls and specifiers becomes relative to toUrl instead of fromUrl.

This function exists in case you need to move an importmap file somewhere else in the filesystem. This is not a common use case but might happen.

import { moveImportMap } from "@jsenv/import-map"

const importMapMoved = moveImportMap(
  {
    imports: {
      foo: "./foo.js",
    },
  },
  "file:///project/project.importmap",
  "file:///project/dir/project.importmap",
)
console.log(JSON.stringify(importMap, null, '  ')

{
  "imports": {
    "foo": "../foo.js",
  }
}

— source code at src/moveImportMap.js.