Reference

Changelog

Every importmap-plus release, from the gem's own CHANGELOG.md.

Releases#

2.1.0

Added

  • Every app's map is finalized once it has booted, in every environment. After initialization the engine calls the new Importmap::Map#finalize!: every pin and directory is deeply frozen, Ractor-shareable on Ruby 3+ (but for a pinned value no Ractor can share, below), and so is every set of pins the map publishes after it. A development reload, the cache sweeper, and a pin or draw after boot work as before, each publishing a new, frozen set, so nothing that pins or reloads starts raising. Importmap::Map#finalized? says whether a map has been. Outside the engine (an Importmap::Map.new passed to the helpers) finalize! is yours to call.

Changed

  • Behaviour change: the pins are frozen once the app has booted. Changing one in place, such as importmap.packages["md5"].preload = false, raises FrozenError in development and test as well as production. Change the map with pin, pin_all_from and draw; an app that can't sets config.importmap.finalize = false, which leaves its pins unfrozen.
  • A pinned value no Ractor can share is kept as it is, never raised on. A pin whose to: is an object holding a lock, a logger or a lambda over the app's state stays the object the app gave, unfrozen, and works on the main Ractor only; its pin and every other pin are still frozen. The same goes for the class-level URIs below.
  • Importmap::Map#packages and #directories return frozen hashes, the current generation's (see the reload fix below). Change the map with pin, pin_all_from and draw.
  • The class-level URIs are stored deeply frozen. Packager.endpoint, Packager.esm_run_resolver (EsmRun.resolver) and Npm.base_uri are set once, in an initializer; the URI you assign is frozen in place, so no thread can change it under another. The default minifier is looked for when importmap/packager loads rather than on first use; one you set, a lambda over your own state included, is kept as given, and nil puts the default back.
  • Every Ruby file in the gem has # frozen_string_literal: true, but for the two install templates copied into an app (bin/importmap and config/importmap.rb), which are the app's files.

Fixed

  • A request during a reload renders a whole map. The reloader re-evaluated config/importmap.rb into the map every request reads, one pin at a time, so a request mid-reload could render half of the new map and half of the old. Every change now builds the next pin set on a copy and swaps it in whole, and a draw that raises leaves the map it started from. A reload still adds to the map, as before.

  • A render no longer caches the map from before a change. The rendered JSON and preloads were memoised with an unlocked check-then-set that a pin, enable_integrity! or the cache sweeper reset underneath: a render that started first finished after the reset and cached the old map until the next change. Each render is now cached in the pin set it read, under a lock, and renders that miss together all get the one that was kept.

2.0.2

Fixed

  • doctor leaves a bundle installed inside the app alone. A file an engine serves out of its gem is skipped, because no bin/importmap command can fix it — but "out of its gem" was read as "outside the app root". With bundle config set path vendor/bundle, as a CI caching its gems has, the gems are under the root, so an engine's controller importing a package the app never pinned failed doctor in CI and nowhere else. Files under Gem.path or Bundler.bundle_path are now skipped wherever they sit.

  • A preload: %w[...] survives a rewrite. pin, update and pristine carried over preload: ["admin", "app"] but not the same list written as a word array, which RuboCop and Standard prefer (Style/WordArray). The option was dropped without a word, so an updated package quietly stopped being preloaded on the pages that named it. It is now read — backslash escapes and nested brackets included, so %w[my\ app] is the one entry point Ruby sees and %w[foo [bar]] keeps its [bar] — and written back in the form the app chose:

    pin "tailwindcss-stimulus-components", preload: %w[application webcad] # @6.1.3
    # after bin/importmap update
    pin "tailwindcss-stimulus-components", preload: %w[application webcad] # @6.1.4
  • A quoted preload keeps a bracket or quote inside it. preload: ["a]", "b"] was cut at the first ] and preload: "it's" at the ', so a rewrite wrote back a shorter list or a different entry point. Quoted strings are now read whole, and a quoted preload — one entry point or a bracketed list — is written back exactly as the app wrote it, quotes included, so "\u0061pp" stays the app entry point and "#{prefix}app" still interpolates (both used to come back as a different name). preload: 'say "hi"' no longer becomes "say "hi"".

2.0.1

Fixed

  • bin/importmap doctor no longer reports comments and prose as unpinned imports. The import scanner read from "…" and import "…" wherever the text appeared, so a line comment such as // e.g. 'en' from 'en-US' and strings such as turbo_power's `…provided in the "from" attribute for the "…` came back as error … imports " attribute for the ", which isn't pinned. Line comments are now discounted before scanning (strings and regex literals are still consumed whole, so "https://…" is safe), and a quoted text that can't be a module specifier — whitespace, a backtick, a ${ interpolation, or no word character at all — is not reported.

1.2.0

Added

  • pin resolves the version on the npm registry, then falls back from jspm to esm.run to jsDelivr. jspm is the default CDN and was the only one pin asked, so a package its generator can't build — [email protected] fails on a cytoscape subpath, @mui/[email protected] on a module it can't find — ended in Couldn't find any packages, and a bare pin foo took whatever version jspm had indexed, which lags npm. A package that names no CDN of its own is now asked of each in turn, and its version is settled against the registry before any of them is asked:

    $ bin/importmap pin mermaid
    Resolved "mermaid" to 10.6.0 from the npm registry
    jspm couldn't resolve "[email protected]" (No './dist/cytoscape.umd.js' exports subpath defined in [email protected]); trying esm.run
    Pinning "mermaid" to vendor/javascript/mermaid.js via download from https://cdn.jsdelivr.net/npm/[email protected]/+esm
    pin "mermaid" # @10.6.0 (esm.run)

    The pin comment already records a CDN that isn't jspm, so update and pristine stay on esm.run from then on with no new state anywhere. An explicit --from, and a provider a pin already names, are choices somebody made: those are asked once and never fall back. When no CDN has the package, each one's reason is printed and the summary names all three.

  • A download that isn't an ES module is kept remote instead of vendored. The CDNs that serve a package's own dist file hand back the UMD bundle plenty of packages still publish; vendored into an import map it runs and exports nothing, so import x from "pkg" fails to link in the browser and nowhere else. pin google-libphonenumber --from jsdelivr now keeps the pin remote and records (remote: not an ES module). --vendor downloads it anyway, and the default pin never sees it, since jspm converts the package.

  • The CDN's own reason reaches the terminal. jspm answers 401 with its generator's message in the body, which pin discarded: Couldn't find any packages in ["[email protected]"] on jspm said nothing about what went wrong. That message is now printed with the sentence, whichever CDN was asked.

  • pin keeps a package remote when its file can't stand alone, and says why. A vendored package is one file served under a digested asset path, but plenty of packages ship a file that imports a sibling by relative path, spawns a Worker, reads import.meta.url or fetches a .wasm binary — every one of those 404s in the browser, and importmap-rails vendors it anyway. pin now reads the download before writing anything to vendor/javascript; a file that needs more than itself is pinned to its CDN URL and the reason goes on the pin:

    $ bin/importmap pin [email protected]
    Pinning "fflate" to https://ga.jspm.io/npm:[email protected]/esm/browser.js (kept remote: workers)
    pin "fflate", to: "https://ga.jspm.io/npm:[email protected]/esm/browser.js" # @0.8.2 (remote: workers)

    The pin then behaves like any other remote pin — pin and update re-resolve it from the same CDN and keep the reason, pristine skips it. pin --vendor downloads the package anyway and records (vendored) on the pin, so a later update doesn't undo the override; it also converts a pin that was kept remote back to a download. Nothing an app already vendored is rewritten on its own — pristine redownloads those pins as it always has — but the next pin or update that touches one re-resolves it, and a package whose file can't stand alone converts to a remote pin then. That is the fix arriving, not a surprise: the vendored file it replaces was already 404ing for its siblings. pdf.js is the package most apps will see this on — see the upgrading page for what to expect and how --vendor puts it back.

  • A pin that stays remote carries a subresource-integrity hash. A vendored file is served by the app; a remote pin is fetched from a CDN on every page load with nothing checking the bytes, and importmap-rails never wrote an integrity: value for one — the hash had to be computed by hand and redone on every update. pin --remote, and a package kept remote because its file can't stand alone, now fetch the URL they just resolved, hash it and write it with the pin:

    $ bin/importmap pin [email protected] --remote
    Pinning "md5" to https://ga.jspm.io/npm:[email protected]/md5.js (integrity sha384-+wqk6m3DPZ6mVMgVZlXnGgDjDY2skGEZ3U9tBnRHiPJXLRLKBmYkKlX2urz9T61b)
    pin "md5", to: "https://ga.jspm.io/npm:[email protected]/md5.js", integrity: "sha384-+wqk6m3DPZ6mVMgVZlXnGgDjDY2skGEZ3U9tBnRHiPJXLRLKBmYkKlX2urz9T61b"

    The hash is sha384 of the bytes the CDN served, computed here rather than asked of any one CDN, so jspm, esm.run, jsDelivr, unpkg, esm.sh and skypack are all covered by one code path. update and a later pin fetch the new URL and rewrite the hash, so a pin never carries the hash of a file it no longer points at — where before an explicit hash was simply dropped. enable_integrity! in config/importmap.rb is still what puts the value in the import map and on the preload link; --no-integrity skips the fetch for a run, and integrity: false on a pin stays off for good. Vendored downloads are unaffected: integrity: true, the default, already computes theirs through the asset pipeline.

  • pin vendors a package's whole file graph, so a chunked package no longer needs a CDN at runtime. A package whose entry imports a sibling by relative path — @popperjs/core, date-fns, lodash-es, and every package built by a bundler that splits chunks — could not be vendored: the browser resolves ./enums.js against a digested asset path, and neither Propshaft nor Sprockets rewrites import statements. Those packages were kept remote. pin now downloads the closed set of files the entry reaches, rewrites every relative specifier to a bare key, and maps the directory with one pin_all_from line:

    $ bin/importmap pin @popperjs/[email protected]
    Pinning "@popperjs/core" to vendor/javascript/@popperjs/core.js via download from https://ga.jspm.io/npm:@popperjs/[email protected]/lib/index.js (with 47 sibling files)
    pin "@popperjs/core", to: "@popperjs--core.js" # @2.11.8
    pin_all_from "vendor/javascript/@popperjs--core", under: "@popperjs/core", to: "@popperjs--core" # @2.11.8 (graph of @popperjs/core)

    The entry keeps the flat file and the plain comment it always had, so update, outdated, lock and pristine read it exactly as before, and a config/importmap.rb written this way still parses under importmap-rails. Bare specifiers are untouched, and a file that is another pin's own entry is rewritten to that pin's key rather than copied, so the browser evaluates each module once. (Two pins of one package do each carry their own copy of a chunk they share; both write it under the same key, so one of the copies is what every importer gets and the other is dead weight.) unpin takes the directory and the line with the pin, pristine rebuilds the directory, pin --minify minifies every file in it, and pin --vendor downloads the entry on its own and drops the directory and line it had. A directory the import map doesn't map as one of ours is the app's: pin says so, writes nothing rather than renaming it away, and exits non-zero — as it does when a CDN fails partway through a crawl, where the pin and the files it had are left exactly as they were.

    Only jspm, jsDelivr and unpkg are crawled — their URLs say where a package's directory ends. A graph that can't be taken over whole (a relative path that climbs out of the package, a sibling the CDN hasn't got, a sibling that isn't JavaScript, two files that would collapse to one key) keeps the whole package remote, as does a download that also spawns a worker, reads import.meta.url, computes an import() or names a .wasm file. A pin importmap-plus had kept remote for its relative imports is converted back to a download by the next pin or update, on the CDN its URL names.

    Two things pin says out loud rather than doing quietly: a key some other package's graph already maps (a directory wins over a pin, so the pin would do nothing), and a second directory mapping a package one already maps at another version (a file they share resolves to one of them).

  • bin/importmap doctor checks an app's import map and vendored files, offline. audit and outdated ask the npm registry about your packages; nothing asked whether the map still matched the files in the repo. A pin whose file had gone missing, a vendored file importing a bare specifier nobody pinned, a vendored file still importing the siblings it was downloaded beside, a CommonJS bundle a CDN handed back — each of those said so in the browser and nowhere else. doctor boots the app and reports them:

    $ 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

    Errors exit 1, so it belongs in CI beside audit and outdated; warnings — a file nothing serves, including a .mjs that pin_all_from never picks up, and two keys on one file or one package vendored at two versions — leave the exit status alone. It reports and never edits: pin, unpin and pristine are what fix what it finds.

    --online adds the one check that needs the network, fetching every remote pin to report one the CDN no longer serves and an integrity: hash that doesn't match the bytes it does serve. Every other check reads only the map, the asset paths and the files on disk, so the default is fast and can't fail because a CDN is having a bad afternoon.

  • config.importmap.preload_strategy = :reachable preloads what the entry point actually reaches. Every pin with preload: true gets a modulepreload link on every page, so a package the app only loads with import() is fetched up front anyway unless someone writes preload: false on it — and on everything it depends on, and keeps that list right as the package changes. An app on this gem carried the comment "imported only by apexcharts.js, which is itself lazy. Without it, 1.1 MB was preloaded on every page."

    The import graph already knows. app/javascript, vendor/javascript and every pin_all_from directory are files on disk, and their import statements name pin keys:

    # config/application.rb
    config.importmap.preload_strategy = :reachable

    javascript_importmap_tags "application" now emits a link only for the pins application reaches through static imports, however deep. A dynamic import() is the lazy boundary and contributes nothing — preloading its target is the deferral the app asked for, undone. A pin naming an entry point (preload: "admin") is preloaded whether or not the graph reaches it, which is the escape hatch for a specifier no regex can see; preload: false stays off either way.

    Nothing new happens on the request path: the files are the ones the asset pipeline already serves, read once per import map cache generation and dropped by the same sweeper that drops the rendered map when a .js file changes. The default :all — upstream's behaviour, one link per preload: true pin — is unchanged and never opens a file.

  • javascript_importmap_tags sends its modulepreload links as 103 Early Hints. A modulepreload link is markup, so the browser can only act on it once the HTML has streamed far enough to be parsed — the whole module graph waits on the response. The same list now goes out ahead of it as a Link header, and the fetches start while the app is still rendering:

    HTTP/1.1 103 Early Hints
    Link: </assets/application-abc.js>; rel=modulepreload, </assets/@hotwired--stimulus-def.js>; rel=modulepreload

    Exactly the modules the tags preload, so preload: false, an entry point's own list and preload_strategy = :reachable all narrow the hinted set with the tags. No integrity parameter: browsers don't honour one on a Link header, and the tag in the body still carries it.

    This is what Rails' own javascript_include_tag and stylesheet_link_tag already do, and it needs what they need — a server that puts rack.early_hints in the env, which Puma does with early_hints true. On a server without it, send_early_hints is a no-op and nothing changes. Off with config.importmap.early_hints = false.

Changed

  • Everything this gem knows about esm.run lives in Importmap::EsmRun. The provider name, the bundle URL shapes, the rewrite that turns a bundle's /npm/dep@ver/+esm imports into bare specifiers and the jsDelivr version lookup were nine things in Importmap::Packager, which had grown to the 800-line ceiling with nowhere to put the next addition. Behaviour is unchanged and no documented setting moved: Importmap::Packager.esm_run_resolver still reads and writes the resolver, now on the new class. Only the :nodoc: constants Packager::ESM_RUN_* are gone, as Importmap::EsmRun::PROVIDER, ::CDN, ::URL_REGEXP and ::IMPORT_REGEXP.

Fixed

  • One package a CDN can't resolve no longer blocks — or silently moves — the rest of the batch. (#32) A CDN answers a batch of packages as a whole, so bin/importmap update with three outdated packages reported Couldn't find any packages in ["cheap-ruler", "mapbox-gl", "mermaid"] on jspm, updated nothing and exited 0, because jspm's generator can't build mermaid. Commenting out the one package let the other two through. A refused batch of more than one package is now asked for one package at a time, along the path each would have taken alone:

    $ bin/importmap pin [email protected] [email protected]
    jspm couldn't resolve "[email protected]", "[email protected]" (No './dist/cytoscape.umd.js' exports subpath defined in [email protected]); asking for each on its own
    Pinning "md5" to vendor/javascript/md5.js via download from https://ga.jspm.io/npm:[email protected]/md5.js
    jspm couldn't resolve "[email protected]" (No './dist/cytoscape.umd.js' exports subpath defined in [email protected]); trying esm.run
    Pinning "mermaid" to vendor/javascript/mermaid.js via download from https://cdn.jsdelivr.net/npm/[email protected]/+esm
    pin "md5" # @2.2.0
    pin "mermaid" # @10.6.0 (esm.run)

    Only the package the CDN refused travels the rest of the chain, so a healthy package is never re-pinned from another CDN — and never has its provenance comment rewritten — because a sibling failed. An explicit --from, or a provider a pin records, still asks that one CDN and only that one, now once per package. The batch stays the fast path: it is split only when it is refused and holds more than one package.

    pin, update and pristine now exit 1 when a package was left unresolved, so bin/importmap update && git commit can no longer commit an import map that quietly missed a package. The packages that did resolve are still written.

  • A CDN that fails mid-crawl leaves the pin alone. Vendoring a graph makes one request per file — 250 of them for date-fns — so a 503 that outlives the retries is far likelier than it was for a single download. pin and pristine report it (Skipping "date-fns": Unexpected response code (503)) and change nothing, rather than taking it for "this package can't be vendored" and converting a working pin to a remote one, which would delete the very files that make it work.

  • pristine reports a package it can't restore and carries on. It is the repair command, and a pin whose graph the CDN no longer serves the way the pin describes now raises where nothing used to — unrescued, that ended the whole run with a backtrace and left every package after it unrestored. Each one that fails is reported (Couldn't restore "pdfjs-dist": it can't be vendored as a single file (workers)), the rest are restored, and 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.

  • A download the CDN encoded in a way Net::HTTP can't undo is fetched again. jspm answers some files with content-encoding: br whatever the request advertises, and Net::HTTP decompresses gzip and deflate only: @popperjs/[email protected]/lib/utils/computeAutoPlacement.js arrived as brotli bytes, which read as invalid UTF-8 and took the source inspection down with ArgumentError: invalid byte sequence in UTF-8. pin now repeats that one request asking for an unencoded body. It doesn't ask up front: supplying an Accept-Encoding at all stops Net::HTTP decoding the gzip it does understand. Inherited from importmap-rails, which downloads the same way.

  • Importmap::Packager::ServiceError is a class again. It was assigned Error.new(Error) — an instance — so rescue Packager::ServiceError raised TypeError: class or module required for rescue clause, and every jspm service error arrived as a plain Packager::Error. Inherited from importmap-rails, where it is still the case.

  • A failed download no longer deletes the file an app already has. pin and pristine removed vendor/javascript/<package>.js before fetching, so a CDN that answered 500 — or, now, a file that can't be vendored — left the app with no file at all. The existing file is replaced only once the new one has arrived and been found fit to serve.

  • update <package> moves every pin of that package, not just the bare one. An app with pin "pdfjs-dist" and pin "pdfjs-dist/build/pdf.worker.min.mjs" ran update pdfjs-dist and got a new main file next to a worker still at the old version — the two are built together and don't tolerate that. A package name now means every key that carries it, the same set outdated reports and a bare update moves; update pdfjs-dist/build/pdf.worker.min.mjs still means that one key.

  • A subpath pin without a CDN in its comment resolves from the CDN its package's pin names. The worker pin above, written before provenance existed, was sent to jspm — which can't resolve pdf.js at all — and reported "Couldn't find any packages" on every update while the main pin moved on from jsdelivr. Siblings pinned together come from the same place; the next update records it on the pin. A pin answers for itself first — its own comment, then its own to: URL — and only then does its package answer for it, whether that pin is vendored, recording the CDN in its comment, or remote, carrying it in the URL with no comment at all.

  • An array preload: survives a rewrite however it is quoted, and preload: [] stays preload: []. The option was read back through JSON.parse, so pin 'md5', preload: ['admin'] — single quotes being a supported pin shape everywhere else in this gem — took down every command that reads a pin with JSON::ParserError: unexpected character. And preload: [] matched nothing at all, so pin, update and pristine dropped it and quietly restored the preload: true default on a package the app had asked to preload for no entry point. config/importmap.rb is Ruby, not JSON: the entry points are scanned out of the literal now, and an empty array is written back as one.

  • pin --vendor leaves a pin to a custom URL alone. --vendor is meant to override the check that refuses a download, not the URL an app chose to pin, but it reached the vendoring path before the branch that skips custom URLs could run: bin/importmap pin md5 --vendor against pin "md5", to: "https://cdn.example.com/md5.js" downloaded md5 from whichever CDN the spec resolved to and replaced the line with pin "md5" # @2.3.0 (vendored), without a word about the URL it had just dropped. It now reports the skip the way a plain pin does and names the flag in it. Moving such a pin on purpose is still --from, which re-resolves it from the CDN you name.

1.1.0

Added

  • Version locks. bin/importmap pin [email protected] --lock, or bin/importmap lock luxon for a package already pinned, records the lock in the version comment — pin "luxon" # @3.7.2 (locked) — and update and a plain pin skip the package from then on, saying so. A remote pin gains the comment too, carrying the version from its URL. pin --force moves a locked package and keeps the lock at the new version; --no-lock drops it; bin/importmap unlock luxon removes it without touching the file. pristine still redownloads a locked vendored package, at the locked version; remote pins are skipped as always. Only the packages named on the command line are locked, never the dependencies a CDN resolves with them, and a locked dependency stays where it is when the package that needs it is pinned or updated.
  • update takes package names, --all and --force. bin/importmap update luxon stimulus-use re-pins just those, asking the registry about them alone; update --all says explicitly what a bare update has always done. A named package that is up to date, or has no version to compare, is reported; a name with no pin stops the command before anything is touched. --force updates locked packages too and keeps each lock at the new version.
  • outdated shows locks. A new Locked column marks packages held at their version, and the command exits 1 only when an unlocked package is outdated, so CI stays green for the versions the app chose.
  • integrity: true and integrity: false survive a rewrite. An update, pristine or pin used to drop the option; only an integrity hash, which belongs to the old file, is still removed when the URL changes.

Fixed

  • update no longer re-pins a package the registry couldn't be checked for. A package whose registry lookup came back unusable has no latest version, so nothing established that it moved — but update re-pinned it anyway, letting a bad answer re-resolve the pin against the CDN and carry it to a version nobody asked for. Those packages are now reported — Couldn't check "md5": Unexpected error response 500: … — and left where they are; every other package still updates, and the command exits 1. Inherited from importmap-rails, where a bare update has always behaved this way.
  • update re-pins a subpath pin instead of appending a bare one. The registry answers about photoswipe, the import map pins photoswipe/lightbox, and a bare update or update --all used to re-pin the name it was answered with: the subpath pin stayed at its old version and a pin "photoswipe" was appended beside it — vendored, since a fresh pin has no provenance to say otherwise. Every key carrying an outdated package is now re-pinned, and a package pinned under several keys moves all of them. Only pins that declare a version take part, the same ones outdated reports on, so an app file pinned under a package's namespace — pin "md5/helpers", to: "md5/helpers.js" — is left alone. Inherited from importmap-rails; update photoswipe/lightbox was fixed for the named form in 1.1.0.
  • A remote subpath pin is re-resolved from the CDN it is on. Moving pin "photoswipe/lightbox", to: "https://cdn.jsdelivr.net/npm/[email protected]/…" back onto jsDelivr asked for photoswipe/[email protected], a path no CDN has, so update gave up with Keeping "photoswipe/lightbox" pinned to … (couldn't resolve it from jsdelivr) and the pin never moved. The version now goes where a CDN expects it, ahead of the subpath — [email protected]/lightbox.
  • A registry that won't answer for one package no longer ends the run. A 404, a 5xx or a connection that kept resetting used to escape outdated_packages once the retries were spent, so outdated and update died with a backtrace and checked nothing else. The failure is now recorded against that package alone — outdated prints the reason in its Latest column, which is what the column was always for — and every other package is still checked. audit is unchanged: a registry it can't reach still fails the command outright.

1.0.0

First release of importmap-plus, a drop-in replacement for importmap-rails 2.2.3. The Importmap:: API, the pin DSL and the generated import map are unchanged; Importmap::UPSTREAM_VERSION names the importmap-rails release this tracks.

Added

  • bin/importmap pin --minify runs a download through bun, esbuild or terser — the first found in node_modules/.bin or on PATH, including Windows .cmd shims — before it lands in vendor/javascript. Always transform-only, so bare import specifiers stay exactly as the CDN resolved them and the import map keeps resolving them. pristine --minify does the same for everything already vendored. Plenty of packages publish unminified ESM (pdfjs-dist, choices.js, luxon), and a CDN serving package files hands them out as published.
  • --from esm.run pins jsDelivr's bundled builds instead of a package's own dist file. A bundle references its dependencies as absolute /npm/[email protected]/+esm imports, which resolve only on jsDelivr; those are rewritten to bare specifiers on download and each dependency without a pin is vendored the same way. A dependency the app already pins is left alone, so the bundle resolves to the version the app chose. Versions resolve through jsDelivr's data API, so pin luxon@3 and pin apexcharts/core work as they do on npm.
  • Provenance in the pin comment. A vendored pin records the CDN when it isn't jspm and whether the file was minified — pin "luxon" # @3.7.2 (esm.run, minified). update, pristine and a plain pin read it back, so a package keeps its CDN and stays minified without repeating the flags. This extends to every CDN: an unpkg download no longer silently moves back to jspm on the next update.
  • An explicit --from moves a remote pin to that CDN, instead of being overruled by the provider the pin already points at.
  • Requests retry. A reset connection, a timeout or a 429/5xx from the CDN is tried up to three times with a growing pause before bin/importmap gives up, and the failure then names the URL instead of a raw backtrace. Importmap::Packager.retry_attempts / retry_wait tune it.

Changed

  • bin/release tags a version and publishes a GitHub Release, which fires .github/workflows/release.yml to push the gem over RubyGems trusted publishing. The upstream script pushed from a developer's machine with an API key.