Overview
A drop-in replacement for importmap-rails with vendoring that keeps its promises.
What it is#
importmap-rails lets a Rails app import JavaScript modules by logical name, straight from the browser, with no bundler. importmap-plus is that gem, forked, with the vendoring story finished: bin/importmap downloads what you ask for, remembers where it came from, minifies it when you say so, and leaves alone what you have locked.
The Importmap:: constants, the pin DSL, config/importmap.rb, the view helpers and the generated import map are unchanged. An app switches by replacing one line in its Gemfile. The importmap-rails release this tracks is in Importmap::UPSTREAM_VERSION.
Importmap:: constants and the same Rails engine.What it adds#
Everything below is bin/importmap; the runtime is untouched.
| Feature | What it does | Docs |
|---|---|---|
pin --minify | Runs a download through bun, esbuild or terser before it lands in vendor/javascript; later updates keep minifying. | Minifying |
--from esm.run | Vendors jsDelivr's one-file bundle, rewrites its imports to bare specifiers, and pins the dependencies it needs. | esm.run bundles |
pin --lock | Holds a package at a version. update, pristine and pin leave it there until you unlock it or pass --force. | Locking versions |
update [PACKAGES] --all --force | Update by name, or everything explicitly; --force moves locked packages and re-locks them. | Updating & auditing |
| Multi-file packages | A package whose entry imports siblings is vendored with its whole file graph; one that needs more than files can give it stays on its CDN, with the reason on the pin. | Multi-file packages |
| Registry-latest and CDN fallback | A version is resolved on the npm registry first, then asked of jspm, esm.run and jsDelivr in turn until one of them has it. | Pinning packages |
doctor | Checks the import map against the files that are actually there, offline, and exits non-zero on an error, so CI can run it. | Updating & auditing |
| Provenance | The pin comment records the CDN, minification and lock, so nothing silently drifts back to jspm. | Provenance |
| Remote pins stay remote | A pin with a CDN URL is re-resolved from that CDN; preload: and boolean integrity: survive every rewrite. | Pinning packages |
| Remote pins hash themselves | A pin left on a CDN carries a subresource-integrity hash of the bytes that were resolved, rewritten whenever the URL moves. | Subresource integrity |
| Requests retry | A reset connection, a timeout or a 429/5xx is tried three times with a growing pause before the command gives up. | Configuration |
What it adds at request time#
Two opt-in settings; the tags are otherwise byte-for-byte upstream's.
| Setting | What it does | Docs |
|---|---|---|
preload_strategy = :reachable | Preloads what the entry point actually imports instead of every preloaded pin, so a package a page never reaches costs nothing. | Preloading |
early_hints | Sends the modulepreload links as a 103 Early Hints response, so the browser starts fetching them before the HTML is rendered. | Preloading |
What stays the same#
The parts of importmap-rails you build on are exactly as upstream ships them:
pin,pin_all_fromandenable_integrity!inconfig/importmap.rb,javascript_importmap_tagsandjavascript_import_module_tagin your layouts,Rails.application.importmap,Importmap::Map, the cache sweeper and the reloader,Rails.application.config.importmap.*,bin/importmap json,audit,outdated,packages,unpinandpristine.
Those pages of these docs are importmap-rails' own documentation, kept in step with the upstream release this gem tracks.
Where next#
- New app, or an app on importmap-rails today: Installation.
- Coming from importmap-rails and wondering what changes: Upgrading from importmap-rails.
- Every command and flag on one page: CLI reference.