Configuration
The application config the engine reads, and the class-level settings bin/importmap reads.
config.importmap#
Set in config/application.rb or an environment file.
| Option | Type | Default | Description |
|---|---|---|---|
paths | Array<Pathname> | [] | Import map files, drawn in order. The engine appends config/importmap.rb during initialization, so files added in application.rb or an environment file are drawn before it; engines append theirs here. |
sweep_cache | Boolean | true in development and test | Watch the JavaScript directories and clear the rendered map when a file changes. Only takes effect when classes are reloadable. |
cache_sweepers | Array<Pathname> | [] — app/javascript and vendor/javascript are added when the watcher is installed | The directories the watcher covers, read once when sweep_cache is on and classes are reloadable. Engines append their JavaScript directories before importmap.cache_sweeper runs. |
rescuable_asset_errors | Array<Class> | the pipeline's missing-asset error | Errors that make a pin resolve to nothing (and log a warning) instead of raising. Propshaft::MissingAssetError and Sprockets' AssetNotFound are added for you. |
preload_strategy | Symbol | :all | Which preload: true pins get a modulepreload link. :all is every one of them, upstream's behaviour. :reachable is only those the entry point reaches through static imports — see Preloading. A pin naming an entry point, and preload: false, mean the same under both. |
early_hints | Boolean | true | Send the modulepreload links javascript_importmap_tags is about to emit as a 103 Early Hints Link header. A no-op unless the server supports it (Puma needs early_hints true) — see Preloading. |
finalize | Boolean | true | Finalize the map once the app has booted, in every environment: every pin is deeply frozen (Ractor-shareable), and so is every set of pins a development reload, the cache sweeper or a later pin publishes, so reloading and pinning work as before. A pinned value no Ractor can share, such as an object holding a lock, is kept as given, on the main Ractor only. Changing a pin in place (packages["md5"].preload = false) raises FrozenError; turn it off if something does. |
config.importmap.sweep_cache = true
config.importmap.cache_sweepers << Rails.root.join("lib/javascript")Importmap::Packager#
Class-level settings read by bin/importmap.
bin/importmap loads config/application.rb but not your initializers, so these are set there (or in a file it requires), after require "importmap/packager".
| Option | Type | Default | Description |
|---|---|---|---|
minifier | #call(source) → String | the first of bun, esbuild, terser found | What --minify runs a download through. |
retry_attempts | Integer | 3 | How many times a CDN or registry request is tried. |
retry_wait | Numeric | 0.5 | Seconds between tries, multiplied by the attempt number. |
endpoint | URI | https://api.jspm.io/generate | The JSPM generator API. |
esm_run_resolver | URI | https://data.jsdelivr.com/v1/packages/npm/ | The jsDelivr data API --from esm.run resolves versions through. |
require "importmap/packager"
Importmap::Packager.minifier = ->(source) { MyMinifier.minify(source) }
Importmap::Packager.retry_attempts = 5
Importmap::Packager.retry_wait = 2Importmap::Npm.base_uri (default https://registry.npmjs.org) is where outdated, update and audit ask about versions and advisories; point it at a mirror if your network needs one.
Set these once, at boot. endpoint, esm_run_resolver and base_uri are stored deeply frozen (Ractor-shareable), so the URI you assign is frozen too, unless it holds something no Ractor can share, which is kept as given. A minifier you assign is kept as given too, a lambda over your own state included.
Retries#
CDNs reset connections and rate-limit bursts. A reset connection, a timeout or a 429, 500, 502, 503 or 504 from a CDN or the registry is tried retry_attempts times, pausing retry_wait × attempt seconds between tries, before bin/importmap gives up. A transport failure then says which request it was making; an HTTP error reports the status, or the message the service returned. A 404 is not retried: the package isn't there.