jspm / import-map

Import Map Utility

Import Map Utility

Generic ImportMap class utility for the manipulation and resolution of import maps, used by JSPM.

Getting Started

Installation

Node.js:

npm install @jspm/import-map

Usage

@jspm/import-map only ships as an ES module.

example.mjs

import { ImportMap } from '@jspm/import-map';

const mapUrl = import.meta.url;

const map = new ImportMap({
  mapUrl, // optional
  map: {
    imports: {
      react: 'https://cdn.com/react.js'
    },
    scopes: {
      'https://site.com/': {
        react: 'https://cdn.com/react2.js'
      }
    }
  }
});

// Use the map resolver
map.resolve('react') === 'https://cdn.com/react.js';
map.resolve('react', 'https://site.com/') === 'https://cdn.com/react2.js';

// Supports normal URL resolution behaving a browser-compatible ES module resolver
map.resolve('./hello.js', 'https://site.com/') === 'https://site.com/hello.js';

// Mutate the map
map.set('react', './custom-react.js');
map.resolve('react') === new URL('./custom-react.js', mapUrl).href;

// Mutate the map inside a custom scope
map.set('react', './custom-react2.js', 'https://another.com/');
map.resolve('react', 'https://another.com/') === new URL('./custom-react2.js', mapUrl).href;

// Get the map JSON
console.log(JSON.stringify(map.toJSON(), null, 2));
// {
//   "imports": {
//     "react": "./custom-react.js"
//   },
//   "scopes": {
//     "https://site.com/": {
//       "react": "https://cdn.com/react2.js"
//     },
//     "https://another.com/": {
//       "react": "./custom-react2.js"
//     }
//   }
// }

// Rebase the map
map.rebase('./map/');
console.log(JSON.stringify(map.toJSON(), null, 2));
// {
//   "imports": {
//     "react": "../custom-react.js"
//   },
//   "scopes": {
//     "https://site.com/": {
//       "react": "https://cdn.com/react2.js"
//     },
//     "https://another.com/": {
//       "react": "../custom-react2.js"
//     }
//   }
// }

// Flatten the import map (removes unnecessary scope redundancy)
map.set('react', '../custom-react.js', 'https://site.com/');
map.flatten();
console.log(JSON.stringify(map.toJSON(), null, 2));
// {
//   "imports": {
//     "react": "../custom-react.js"
//   },
//   "scopes": {
//     "https://another.com/": {
//       "react": "../custom-react2.js"
//     }
//   }
// }

// Replace URLs in the map
map.replace('https://cdn.com/', 'https://cdn-mirror.com/');
map.replace('https://another.com/', 'https://another-site.com/');
console.log(JSON.stringify(map.toJSON(), null, 2));
// {
//   "imports": {
//     "react": "../custom-react.js"
//   },
//   "scopes": {
//     "https://another-site.com/": {
//       "react": "../custom-react2.js"
//     }
//   }
// }

// Combine subpaths in the map
// This is only supported for scopes and not top-level imports,
// to avoid losing dependency information from imports.
// (all non-returning methods support chaining)
console.log(new ImportMap({
  map: {
    scopes: {
      "/": {
        "pkg/a.js": "/pkg/a.js",
        "pkg/b.js": "/pkg/b.js"
      }
    }
  }
}).combineSubpaths().toJSON());
// {
//   "imports": {},
//   "scopes": {
//     "/": {
//       "pkg/": "/pkg/"
//     }
//   }
//  }

API

See src/map.ts.

Support is also provided for conditional maps supporting a way to manage generic maps for multiple environment targets, before serializing or resolving for exact environment targets.

License

MIT

import-map's Issues

scope to import flattening option

generate .d.ts files and map to them in package.json

Same issue as: jspm/generator#252

Currently if someone installs the generator they'll get a transitive dependency on @jspm/import-map, and if they have strict typing enabled this will break their project.

scopeToImports feature

It could be useful to have a scopeToImports function which when given a scope URL will flatten that scope into "imports" where possible.

rootURL support for inputMap

When providing an inputMap, it would be useful to support rootURL normalization of the input URLs instead of resolving / to the base of the file system / base of the map base.

Better scope flattening

Need some real examples to work on here, but there may be room for improvement in the multi-scope flattening scenarios.