How do importmap-rails' bin/importmap outdated, audit and update keep vendored pins current, and what does update do with a package first pinned --from jsdelivr?
answer
- versions read from # @x.y.z comments
- outdated and audit exit 1
- audit is a generated CI step
- update always resolves through JSPM
- pristine re-downloads every pin
basics
~20 soutdated compares each pin's # @version comment with the npm registry's latest, audit checks those versions against npm advisories, and both exit 1 on findings. update re-pins outdated packages but always resolves through JSPM, whatever --from was used originally.
solid answer
~40 sAll three read your versions from the `# @x.y.z` comments `bin/importmap pin` wrote; a vendored pin without one is skipped with an "Ignoring ... since no version is specified" message. `outdated` asks the npm registry for each package's latest version, prints a table and **exits 1** if anything is behind. `audit` posts the versions to npm's bulk advisory endpoint, prints vulnerabilities by severity and also **exits 1**; a Rails 8.1 app runs it in the generated `config/ci.rb` and in the `scan_js` job of `.github/workflows/ci.yml`. `update` re-pins each outdated package, downloading the new file into `vendor/javascript` and keeping its `preload:` value, but it calls the resolver with `from: "jspm"` hard-coded, so a package first pinned with `--from jsdelivr` now comes from JSPM. Review the vendored diff before committing.
code
bash · 4 linesbin/importmap outdated # exit 1 when a pin is behind the npm registry
bin/importmap audit # exit 1 when npm advisories match a pinned version
bin/importmap update # re-pin outdated packages via JSPM, keeping preload:
bin/importmap pristine # re-download every pin at its recorded versiongo deeper
Recall that bin/importmap outdated and audit check pinned packages and that update upgrades them.
Explain how the version comment feeds both checks, the exit-1 behaviour, and that update re-resolves through JSPM while keeping preload.
Design the CI routine: audit as a gate, outdated on a schedule, vendored diffs reviewed, and pristine to recover a damaged vendor directory.
Decide whether vendored import-map dependencies give enough supply-chain visibility for the team, or whether a lockfile-based toolchain is warranted.
## Why vendored packages need tooling With **importmap-rails**, third-party JavaScript lives as files in `vendor/javascript`, not as entries in a lockfile that a package manager understands. Something has to know which versions you have, whether newer ones exist and whether any are known to be vulnerable. The `bin/importmap` CLI does that, and it relies on one convention: the `# @x.y.z` comment that `bin/importmap pin` writes at the end of each pin line. ## Where versions come from `Importmap::Npm#packages_with_versions` scans `config/importmap.rb` for: - pins whose `to:` is a CDN URL containing `npm:[email protected]` (or similar unpkg / jsDelivr / Skypack patterns), and - pins with a trailing `# @1.2.3` comment. A vendored pin with **neither** is skipped, and the CLI prints `Ignoring <pkg> (<path>) since no version is specified in the importmap`. So hand-written pins, or comments deleted during a tidy-up, quietly drop out of both checks. ## The commands | Command | What it does | Exit status | |---|---|---| | `bin/importmap outdated` | asks the npm registry for each package's latest version, prints Package / Current / Latest | 1 if any package is outdated | | `bin/importmap audit` | posts package versions to npm's bulk advisories endpoint, prints Package / Severity / Vulnerable versions / Vulnerability | 1 if any vulnerability is found | | `bin/importmap update` | re-pins every outdated package | — | | `bin/importmap pristine` | re-downloads every pinned package at its recorded version | — | | `bin/importmap packages` | prints each package with its version | — | | `bin/importmap json` | prints the resolved import map | — | The non-zero exits are what make `outdated` and `audit` usable as CI gates. ## audit in a new Rails 8.1 app When the app uses import maps, the generator wires the audit in twice: 1. `config/ci.rb` has a step `"Security: Importmap vulnerability audit"` running `bin/importmap audit`, executed by `bin/ci`. 2. `.github/workflows/ci.yml` has a `scan_js` job whose step runs `bin/importmap audit`. `outdated` is not wired in by default; teams that want upgrade pressure add it themselves, often as a scheduled job rather than a gate on every push, because a new upstream release would otherwise fail unrelated builds. ## What update actually does `Importmap::Commands#update`: 1. Collects outdated packages through the same npm registry check `outdated` uses. 2. Reads each one's existing `preload:` value from `config/importmap.rb`, so `preload: false` or `preload: "booking"` survives. 3. Calls the resolver with `env: "production"` and **`from: "jspm"`** — fixed values, not the options you used when pinning. 4. Downloads each resolved file into `vendor/javascript`, replacing the old one, and rewrites the pin line with the new version comment. The trap: a package originally pinned `--from jsdelivr` or `--from unpkg` is re-fetched from JSPM, which may serve a differently built file. If the provider matters, re-run `bin/importmap pin <pkg> --from jsdelivr` instead of `update`. ## A working routine - Run `bin/importmap audit` on every CI build; it is already in the generated configuration. - Run `bin/importmap outdated` on a schedule and treat its exit status as a reminder, not a merge blocker. - Upgrade with `update` (or a targeted `pin`), then read the diff under `vendor/javascript` like any other third-party code change, and exercise the pages that use the package. - If `vendor/javascript` gets edited by hand or partly lost, `bin/importmap pristine` restores every file at its recorded version. - Keep the `# @version` comments; without them none of the above sees the package. ## Reading the output `outdated` prints a three-column table — Package, Current, Latest — and a summary line such as `2 outdated packages found`. A package the registry could not answer for appears with an error in the Latest column instead of a version, which usually means a mistyped or private name. `audit` prints Package, Severity, Vulnerable versions and the advisory title, then a summary that counts findings by severity, for example `3 vulnerabilities found: 2 moderate, 1 high`. The `Vulnerable versions` range tells you whether `update` will clear the finding: if the latest release is still inside the range, upgrading alone does not help and the package may need replacing. Both checks talk to the public npm registry, so they need network access in CI and they report on the npm package, not on the exact file a CDN served. That is another reason to read the vendored diff an `update` produces rather than trusting the version number alone.
- A teammate hand-wrote pin "campsite-icons", to: "campsite-icons.js" for a vendored file. Will audit check it?No. `audit` and `outdated` only see versions from a CDN URL in `to:` or a trailing `# @x.y.z` comment. Without either, the CLI prints that it is ignoring the package because no version is specified. Re-pin it with `bin/importmap pin`, or add the comment if it really is an npm package at that version.
- Why might you not make bin/importmap outdated a required CI step?It exits 1 whenever any upstream package publishes a newer version, so builds would start failing on days when nobody changed the code. `audit` signals a known vulnerability and fits a gate; `outdated` fits a scheduled job or a periodic reminder.
- bin/importmap update keeps using the CDN each package was originally pinned from
- audit reads versions from a package-lock.json the pin command generates
- outdated only prints a table and always exits 0
- A vendored pin without a version comment is still audited by file hash
- update drops preload: options and re-pins everything as preloaded