# @jspm/import-map

> Package Import Map Utility

Latest version **1.5.0** (published 2026-04-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @jspm/import-map
pnpm add @jspm/import-map
yarn add @jspm/import-map
bun add @jspm/import-map
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.5.0 |
| Published | 2026-04-01 |
| First published | 2021-07-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 228.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3867 |
| Author | Guy Bedford |
| Maintainers | guybedford, jkrishna, bubblyworld |
| Keywords | jspm, import maps, es modules |

## Links

- npm: https://www.npmjs.com/package/@jspm/import-map
- Repository: https://github.com/jspm/jspm
- Homepage: https://github.com/jspm/jspm/tree/main/import-map#readme
- Issues: https://github.com/jspm/jspm/issues
- npm.io page: https://npm.io/package/@jspm/import-map

## Recent versions

- 1.5.0 (latest) — 2026-04-01
- 1.4.0 — 2026-03-15
- 1.3.0 — 2026-03-02
- 1.2.2 — 2025-10-12
- 1.2.1 — 2025-08-24
- 1.2.0 — 2025-05-19
- 1.1.0 — 2024-07-07
- 1.0.8 — 2024-03-19
- 1.0.7 — 2023-03-11
- 1.0.6 — 2023-03-08
- 1.0.5 — 2023-02-22
- 1.0.4 — 2022-07-18
- 1.0.3 — 2022-07-17
- 1.0.2 — 2022-07-17
- 1.0.1 — 2022-07-17
- … 13 more at https://npm.io/package/@jspm/import-map/versions

## README

# 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
```js
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'
      }
    },
    integrity: {
      'https://cdn.com/react.js': 'sha384-...'
    }
  }
});

// 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"
//     }
//   },
//   "integrity": {
//     "https://cdn.com/react.js": "sha384-..."
//   }
// }

// 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"
//     }
//   },
//   "integrity": {
//     "https://cdn.com/react.js": "sha384-..."
//   }
// }

// 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"
//     }
//   },
//   "integrity": {
//     "https://cdn.com/react.js": "sha384-..."
//   }
// }

// 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"
//     }
//   },
//   "integrity": {
//     "https://another.com/react.js": "sha384-..."
//   }
// }

// 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](https://github.com/jspm/import-map/blob/main/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

---
_Source: https://npm.io/package/@jspm/import-map · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._