@jsenv/import-map

jsenv-import-map

importMap programmatic implementation

Introduction

jsenv-import-map is a javasScript implementation of the importMap specification. It is written using es modules and is compatible with Node.js.

I made this project because jsenv uses importMap but they are not yet available in browsers.

— see importMap spec

@jsenv/import-map has the following exports:

• applyImportMap
• composeTwoImportMaps
• normalizeImportMap
• resolveImport
• resolveSpecifier
• wrapImportMap

applyImportMap

takes { importMap, href, importerHref } and returns either the href remapped by importMap or the original href.

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

const href = "http://domain.com/foo"
const importMap = {
  imports: {
    "http://domain.com/foo": "http://domain.com/bar",
  },
}
const hrefRemapped = applyImportMap({
  href,
  importMap,
})
console.log(hrefRemapped)

The code above logs "http://domain.com/bar".
The provided importMap specifiers must be absolute and sorted to work as expected.
You can use normalizeImportMap to do that.

— see applyImportMap source code

composeTwoImportMaps

takes (leftImportMap, rightImportMap) and returns an importMap being the composition of the two.

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

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

console.log(importMap.imports.foo)

The code above logs "whatever".

— see composeTwoImportMaps source code

normalizeImportMap

takes (importMap, href) and returns an importMap where relative specifier are resolved against href and sorted.

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

const importMap = {
  imports: {
    foo: "http://cdndomain.com/bar",
  },
}
const href = "http://mydomain.com"
const importMapNormalized = normalizeImportMap(importMap, href)

console.log(importMapNormalized.imports["http://mydomain.com/foo"])

The code above logs "http://cdndomain.com/bar".

— see normalizeImportMap source code

resolveImport

takes { specifier, importer, importMap, defaultExtension } and returns a url.

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)

The code above logs "http://domain.com/main.js".

— see resolveImport source code

resolveSpecifier

takes (specifier, importer) and returns specifier resolved against importer.

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

const specifier = "../file.js"
const importer = "http://mydomain.com/folder/index.js"
const specifierResolved = resolveSpecifier(specifier, importer)

console.log(specifierResolved)

The code above logs "http://mydomain.com/file.js".

— see resolveSpecifier source code

wrapImportMap

takes (importMap, folderRelativeName) and returns an importMap wrapped inside folderRelativeName.

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

const importMap = {
  imports: {
    foo: "bar",
  },
}
const folderRelativeName = "/dist"
const importMapWrapped = wrapImportMap(specifier, importer)

console.log(importMapWrapped.imports.foo)

The code above logs "/dist/bar".
This feature is not part of the spec but is usefull to redirect your imports inside a given folder.

— see wrapImportMap source code

Installation using npm

To install @jsenv/import-map you need to configure npm to use github registry for this package.

1. Configure npm authentification

Github registry requires an authentification token. If you haven't configured it already, read how in the documentation below.

— see Authenticating to GitHub Package Registry documentation on GitHub

For the record, you can save your token with this command

npm config set '//npm.pkg.github.com/:_authToken' 'personal-access-token'

1. Configure npm registry

Run the command below to use github registry for @jsenv/import-map

npm config set @jsenv:registry https://npm.pkg.github.com

1. Run install command

npm install @jsenv/import-map@5.2.0

Installation using yarn

Same steps as Installation using npm replacing step 3 by

yarn add @jsenv/import-map@5.2.0