Getting started

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.

One or the other
Install importmap-plus or importmap-rails, never both — they define the same Importmap:: constants and the same Rails engine.

What it adds#

Everything below is bin/importmap; the runtime is untouched.

FeatureWhat it doesDocs
pin --minifyRuns a download through bun, esbuild or terser before it lands in vendor/javascript; later updates keep minifying.Minifying
--from esm.runVendors jsDelivr's one-file bundle, rewrites its imports to bare specifiers, and pins the dependencies it needs.esm.run bundles
pin --lockHolds a package at a version. update, pristine and pin leave it there until you unlock it or pass --force.Locking versions
update [PACKAGES] --all --forceUpdate by name, or everything explicitly; --force moves locked packages and re-locks them.Updating & auditing
Multi-file packagesA 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 fallbackA 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
doctorChecks 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
ProvenanceThe pin comment records the CDN, minification and lock, so nothing silently drifts back to jspm.Provenance
Remote pins stay remoteA pin with a CDN URL is re-resolved from that CDN; preload: and boolean integrity: survive every rewrite.Pinning packages
Remote pins hash themselvesA pin left on a CDN carries a subresource-integrity hash of the bytes that were resolved, rewritten whenever the URL moves.Subresource integrity
Requests retryA 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.

SettingWhat it doesDocs
preload_strategy = :reachablePreloads what the entry point actually imports instead of every preloaded pin, so a package a page never reaches costs nothing.Preloading
early_hintsSends 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_from and enable_integrity! in config/importmap.rb,
  • javascript_importmap_tags and javascript_import_module_tag in your layouts,
  • Rails.application.importmap, Importmap::Map, the cache sweeper and the reloader,
  • Rails.application.config.importmap.*,
  • bin/importmap json, audit, outdated, packages, unpin and pristine.

Those pages of these docs are importmap-rails' own documentation, kept in step with the upstream release this gem tracks.

Where next#