Reference
CLI reference
Every bin/importmap command, its options, and its exit status.
Commands#
| Command | What it does | Docs |
|---|---|---|
pin [PACKAGES] | Resolves each package's version on the npm registry and the package itself on a CDN, downloads it to vendor/javascript with the sibling files it imports (or pins the URL, with --remote or because the download can't stand alone) and writes the pin. | Pinning |
unpin [PACKAGES] | Removes the pin, the vendored file and the graph directory it maps. | Pinning |
lock [PACKAGES] | Marks the pins as locked at their current version. No network. | Locking |
unlock [PACKAGES] | Removes the lock marker. No network. | Locking |
update [PACKAGES] | Re-pins the outdated packages: the named ones, or every one. | Updating |
outdated | Lists packages the registry has a newer version of. | Updating |
audit | Lists known vulnerabilities for the pinned versions. | Updating |
pristine | Redownloads every vendored package at its pinned version, graph directories and all. Reports the packages it couldn't restore and exits non-zero. | Updating |
packages | Prints every package with a version, one per line. | Updating |
json | Boots the app and prints the resolved import map as JSON. | Updating |
doctor | Boots the app and checks the import map and the vendored files against what is on disk. Offline unless you pass --online. Exits non-zero on any error. | Updating |
A package spec is name[@version][/subpath]: react, luxon@3, [email protected], apexcharts/core, @hotwired/stimulus@3. lock and unlock take names only.
When pin is given a spec with no version, it is resolved against the npm registry first, then asked of jspm, esm.run and jsDelivr in turn until one of them has it. See Pinning.
pin options#
| Option | Type | Default | Description |
|---|---|---|---|
--from CDN | String | the pin's CDN, else jspm then esm.run then jsdelivr | jspm, unpkg, jsdelivr, esm.sh, skypack or esm.run. Naming one turns off the fallback chain: that CDN is asked once. Also moves a remote pin to that CDN. |
--remote | Boolean | false | Pin the resolved URL instead of vendoring a download; converts a vendored pin. |
--integrity / --no-integrity | Boolean | true | Fetch a pin that stays remote to write a subresource-integrity hash of it. --no-integrity skips the fetch; integrity: false on the pin turns it off for good. Vendored downloads are unaffected. |
--vendor | Boolean | what the pin says | Download the entry file on its own even when it looks like it needs siblings beside it, dropping the graph directory it had; converts a pin that was kept remote. Applies only to the packages you name, not the dependencies resolved with them, and --remote wins if you pass both. Recorded on the pin. |
--minify / --no-minify | Boolean | what the pin says | Run the download through bun, esbuild or terser. Recorded on the pin. |
--lock / --no-lock | Boolean | what the pin says | Lock the named packages at this version, or drop their lock. Dependencies are never locked. |
--force | Boolean | false | Re-pin locked packages, keeping each lock at the new version. |
--preload VALUE | String, repeatable | the pin's preload | true, false, or an entry point name; repeat for several entry points. |
--env ENV | String | production | The jspm environment condition (production or development). |
update options#
| Option | Type | Default | Description |
|---|---|---|---|
--all | Boolean | false | Update every outdated package — what a bare update does; rejected together with names. |
--force | Boolean | false | Update locked packages too, keeping each lock at the new version. |
pristine options#
| Option | Type | Default | Description |
|---|---|---|---|
--from CDN | String | each pin's CDN | Redownload everything from this CDN and record it on each pin. |
--minify / --no-minify | Boolean | what each pin says | Minify every download, or none, and record it. |
--env ENV | String | production | The jspm environment condition. |
doctor options#
| Option | Type | Default | Description |
|---|---|---|---|
--online | Boolean | false | Also fetch every remote pin, reporting one the CDN no longer serves and an integrity: hash that doesn't match the bytes it served. Every other check reads only the map and the files on disk. |
Exit status#
| Command | Exits 1 when |
|---|---|
outdated | an unlocked package is outdated |
audit | a vulnerability is known for a pinned version |
pin / update | a package was skipped — its directory is in the way, or its CDN failed partway through a crawl — while the rest were pinned; the skipped pin is left exactly as it was |
pin / update / pristine | no CDN could resolve a package, its reason printed; the packages that did resolve are still written |
update | a named package has no pin, or names are combined with --all; nothing is updated in either case |
pristine | a package couldn't be restored the way its pin describes, or a dependency of an esm.run bundle was skipped; the rest are restored |
lock / unlock | a named package has no pin, has no version to lock at, or was given with a version |
doctor | any finding is an error; warnings alone exit 0 |
| any | a CDN or registry request fails after three attempts; the message names the URL |