Vendoring

Updating & auditing

Update by name or all at once, see what is outdated, check the registry for advisories, check the app against its own files, and redownload what you have.

update#

bin/importmap update asks the npm registry for the latest version of every package with a version in config/importmap.rb and re-pins the outdated ones. Name packages to update just those, or pass --all to say explicitly that you mean everything:

./bin/importmap update                      # everything outdated, as importmap-rails does
./bin/importmap update luxon stimulus-use   # just those
./bin/importmap update --all                # everything, explicitly
./bin/importmap update --force              # locked packages too, re-locked at their new version

A named package that isn't outdated, or has no version to compare, is reported and left alone. A name with no pin at all stops the command before anything is updated — a typo shouldn't half-update an import map. Names together with --all are rejected.

A package the registry couldn't answer for — a 404, a 5xx, a connection that kept resetting — is reported and left where it is: nothing established that a newer version exists, so re-pinning it would let a registry blip re-resolve it against the CDN. Every other package still updates, and the command exits 1 so a script knows it didn't do all it was asked.

A package its CDN can't resolve is reported with the CDN's own reason and left where it is. It doesn't hold back the rest: the CDN is asked for each package on its own once it refuses the batch, so every package it can build still updates, from the CDN its pin names. The command exits 1 to say it didn't do all it was asked.

A package is re-resolved together with the dependencies its CDN lists for it, so those move as well, keeping their own pin options. Each package comes back from the CDN its pin comment names (Provenance); a remote pin is re-resolved from its provider and stays remote; a locked package is skipped unless you pass --force.

The registry knows a package by name, the import map by key, and update re-pins the keys. A pin "photoswipe/lightbox" is a pin of photoswipe, so it is what moves when photoswipe does — no bare pin "photoswipe" appears beside it. A package pinned under several keys has all of them re-pinned, whether you name it or not: update pdfjs-dist moves pdfjs-dist and pdfjs-dist/build/pdf.worker.min.mjs together, since the two are built together; update pdfjs-dist/build/pdf.worker.min.mjs moves that key alone. Only pins with a version take part, so one of your own files pinned under a package's namespace — pin "md5/helpers", to: "md5/helpers.js" — is left alone.

A subpath pin whose comment names no CDN comes back from the CDN its own to: URL points at, and failing that the one its package's pin names — the worker above was pinned together with pdf.js and comes from the same place, which matters when jspm, the default, can't resolve it. The package's pin answers whether it is vendored, recording its CDN in the comment, or remote, carrying it in the URL.

$ ./bin/importmap update md5 nope
Couldn't find a pin for "nope"

$ ./bin/importmap update md5 application
"md5" is already up to date (2.3.0)
Can't tell whether "application" is outdated: its pin has no version
No outdated packages found

$ ./bin/importmap update md5 luxon
Couldn't check "md5": Response error
Pinning "luxon" to https://cdn.jsdelivr.net/npm/[email protected]/build/es6/luxon.mjs
$ echo $?
1

outdated#

outdated checks the registry and prints a table. It exits 1 when an unlocked package is outdated, so it works as a CI check; locked packages are shown but don't fail it.

$ ./bin/importmap outdated
| Package | Current | Latest | Locked |
|---------|---------|--------|--------|
| luxon   | 3.7.2   | 3.7.3  | yes    |
| md5     | 2.2.0   | 2.3.0  |        |
  2 outdated packages found (1 locked)

A package the registry couldn't answer for is listed with the reason where its latest version would go:

| Package | Current | Latest                                     | Locked |
|---------|---------|--------------------------------------------|--------|
| md5     | 2.2.0   | Unexpected error response 500: Service un… |        |

Both outdated and update only see pins with a version: a # @x.y.z comment or a CDN URL with @x.y.z in it. A vendored file whose pin has no version is reported as ignored.

A registry that won't answer for one package doesn't end the run: the lookup is retried, and if it still fails that package alone is reported — outdated prints the reason in its Latest column, update leaves the pin where it is — while every other package is checked as usual.

audit#

audit sends every pinned package and version to the npm registry's advisory endpoint and prints the vulnerabilities it knows about, exiting 1 if there are any:

$ ./bin/importmap audit
| Package | Severity | Vulnerable versions | Vulnerability                    |
|---------|----------|---------------------|----------------------------------|
| md5     | high     | <42.0.0             | Unsafe hashing                   |
  1 vulnerability found: 1 high

pristine#

pristine redownloads every vendored package at the version it is pinned at — after a bad merge, a corrupted file, or to move everything to another CDN or minify it all:

./bin/importmap pristine
./bin/importmap pristine --from esm.run   # move every vendored package to esm.run
./bin/importmap pristine --minify         # minify everything vendored

Remote pins are skipped, since there is nothing to redownload. A --from or --minify that changes a package's provenance is recorded on its pin, so the next update keeps it.

A package whose pin is followed by a pin_all_from line has its file graph crawled again and the directory rebuilt — that is what restoring such a pin means. pristine restores, it never re-decides: a package pinned as one file stays one file, and gets a graph only when a pin or update gives it one. A --from that moves such a package to a CDN that bundles takes the graph away again, directory and line together; a --from naming a CDN whose files can't be crawled (esm.sh, skypack) can't restore it at all, and is reported rather than leaving an entry whose imports resolve nowhere. See Vendoring the file graph.

A package the CDN can no longer serve the way its pin describes is reported and skipped — Couldn't restore "pdfjs-dist": it can't be vendored as a single file (workers) — and the rest of the packages are still restored; the command exits non-zero to say it didn't do all of it, as it does when a dependency of an esm.run bundle, pinned on the way, had to be skipped, or when the CDN a pin names couldn't resolve the package at all.

doctor#

outdated and audit ask the registry about your packages. doctor asks nothing: it boots the app and checks the import map against the files that are actually there, which is the half nothing else covers. Until it existed, a pin whose file had gone missing said so in the browser and nowhere else.

$ ./bin/importmap doctor
error    pin "not_there" → nowhere.js: no such asset
error    vendor/javascript/shoelace.js imports "lit/decorators.js", which isn't pinned
error    vendor/javascript/popper.js imports "./enums.js" by relative path — run bin/importmap pin @popperjs/core to vendor its files
warning  vendor/javascript/old-lib.js isn't pinned by anything
warning  "@hotwired/turbo" and "@hotwired/turbo-rails" both resolve to turbo.min.js
3 errors, 2 warnings

What it looks for, in the order it reports:

  • a pin the asset pipeline can't resolve — the file named by to:, or by the key, isn't on any asset path;
  • a file the map serves that imports a bare specifier no key defines, whether statically or through import("…"). A specifier under a pinned package — lit/decorators.js where lit is pinned — counts as covered;
  • a vendored file importing a sibling by relative path that isn't beside it, which is what a download from before this gem vendored file graphs looks like;
  • a vendored file that isn't an ES module, which a CDN can still hand back;
  • a file in vendor/javascript that no pin serves, including a .mjs, which pin_all_from never picks up;
  • two keys resolving to one file or URL, and two vendored files holding one package at two versions — two copies of a module are two modules, each with its own state.

The first four are errors and make the command exit 1. The last two are warnings: they cost bytes and cause confusion, but the app still runs, so they leave the exit status alone.

--online adds the one check that needs the network — that every remote pin is still served, and still serves the bytes its integrity hash was computed from:

$ ./bin/importmap doctor --online
error    pin "md5" → https://ga.jspm.io/npm:[email protected]/md5.js: integrity doesn't match what the CDN served
error    pin "charenc" → https://ga.jspm.io/npm:[email protected]/gone.js: the CDN answered 404
2 errors, 0 warnings

doctor reports; it never edits config/importmap.rb or anything under vendor/javascript. pin, unpin and pristine are what fix what it finds — a check that rewrote your files is a check you couldn't run in CI.

packages and json#

packages lists every package with a version, one per line. json boots the app and prints the import map exactly as javascript_importmap_tags would render it, resolved through the asset pipeline:

$ ./bin/importmap packages
luxon 3.7.2
md5 2.2.0

$ ./bin/importmap json
{
  "imports": {
    "application": "/assets/application-abc123.js",
    "luxon": "/assets/luxon-def456.js"
  }
}

Checking the app in CI#

The three checks answer different questions, so a pipeline that runs all of them is a pipeline that catches all three kinds of drift:

CommandAsksNeeds the network
doctorDoes the import map match the files in this repo?No, unless --online
auditIs a pinned version known to be vulnerable?Yes
outdatedHas a pinned package moved on?Yes
.github/workflows/importmap.yml
- name: Check the import map against the repo
  run: bin/importmap doctor

- name: Check for advisories
  run: bin/importmap audit

- name: Check for updates
  run: bin/importmap outdated

doctor is the one worth running on every pull request: it is offline, so it is fast and can't fail because a CDN is having a bad afternoon. audit and outdated both talk to the registry, and outdated exits 1 for any unlocked package that has moved — useful on a schedule, noisy on every commit unless you lock the versions you mean to hold.

Add --online to doctor on the scheduled run instead of the per-commit one. It fetches every remote pin, which is the same tradeoff: it catches a CDN that has dropped a file or started serving different bytes, and it can't be told apart from a CDN outage while it's happening.