skip to content

Import Maps & Pins

importmap-rails maps bare module names to vendored, digested files so the browser loads ES modules with no Node build step. Interviewers probe pinning, preloading and where it stops fitting.

part ofRuby on Railsread it →
on this pageshow

explore

questions

5

In a Rails 8.1 campsite-booking app on importmap-rails, what does bin/importmap pin flatpickr do to config/importmap.rb and vendor/javascript?

level: juniorimportance: must knowfreq 52%

answer

  1. JSPM generator resolves the package
  2. downloads into vendor/javascript
  3. pin line with a # @version comment
  4. --from unpkg or jsdelivr
  5. JavaScript only; CSS is on you

basics

~20 s

bin/importmap pin asks the JSPM API to resolve the package and its dependencies, downloads each file into vendor/javascript, and writes a pin "flatpickr" # @version line into config/importmap.rb. At runtime the app serves those vendored files itself.

solid answer

~40 s

`bin/importmap pin flatpickr` sends the package name to the JSPM generator API (or the CDN named with `--from unpkg` / `--from jsdelivr`) for the `production` environment and gets back a map of every module the package needs. For each one it downloads the file into `vendor/javascript` (a scoped `@scope/pkg` becomes `@scope--pkg.js`), strips the `sourceMappingURL` comment, and appends or replaces a line such as `pin "flatpickr" # @4.6.13`. That version comment is what `outdated` and `audit` read later. You commit `vendor/javascript`; Propshaft digests and serves the files, so no CDN is contacted at runtime. `--preload` writes a `preload:` value onto the pin. Only JavaScript is fetched: the picker's stylesheet has to be vendored and linked separately. `bin/importmap unpin flatpickr` deletes the file and the line.

code

bash · 5 lines
bash
bin/importmap pin flatpickr
# Pinning "flatpickr" to vendor/javascript/flatpickr.js via download from https://ga.jspm.io/npm:[email protected]/...

bin/importmap pin flatpickr --from jsdelivr --preload booking
bin/importmap unpin flatpickr

go deeper

for a junior

Recall that bin/importmap pin downloads into vendor/javascript and appends a pin line, and that both are committed.

for a middle

Explain the JSPM resolution, dependency files, the version comment, the --from and --preload options, and that CSS is not part of it.

for a senior

Show judgement about vendoring: no runtime CDN dependency, reviewable diffs of third-party code, SRI via enable_integrity!, and pristine for recovery.

for a principal

Weigh vendoring third-party modules into the repository against a lockfile-driven package manager for auditability, upgrades and team workflow.

## The scenario A campsite-booking app needs a date picker for arrival and departure dates. The team runs Rails 8.1 with the default import maps and has no Node toolchain, so `npm install` is not an option. The importmap-rails answer is `bin/importmap pin`. ## What the command does, step by step `bin/importmap` is a Thor CLI the installer copies into the app. `pin` takes one or more package names plus three options: `--env` (default `production`), `--from` (default `jspm`) and `--preload` (repeatable). 1. **Resolve.** `Importmap::Packager#import` posts the package list to the JSPM generator API (`https://api.jspm.io/generate`) with the browser/module/production environment and the chosen provider. The response is an import map naming every module required, the package and whatever it imports. 2. **Download.** For each entry, `Packager#download` fetches the URL and writes it to `vendor/javascript/<name>.js`. A `/` in the name becomes `--`, so `@github/hotkey` is stored as `@github--hotkey.js`. The file starts with a comment recording where it came from, and any `//# sourceMappingURL=` line is removed because the map file is not downloaded. 3. **Pin.** `Packager#vendored_pin_for` builds the line, for example `pin "flatpickr" # @4.6.13`. A `to:` is added only when the file name differs from `"#{name}.js"`. If the package was already pinned the line is replaced, otherwise appended. 4. **Report.** The CLI prints `Pinning "flatpickr" to vendor/javascript/flatpickr.js via download from <url>`. The version number in the trailing comment is not decoration: `bin/importmap outdated` and `audit` read it to know which version you have. ## What you commit and what runs in production - Commit **both** `config/importmap.rb` and `vendor/javascript`. The installer creates `vendor/javascript` with a `.keep` file for exactly this. - importmap-rails adds `vendor/javascript` to `config.assets.paths`, so Propshaft treats the file like any other asset: digested on `assets:precompile`, served from `/assets/flatpickr-<digest>.js`. - **No CDN is contacted at runtime.** JSPM, unpkg or jsDelivr matter only while you run the command. ## Using it in the booking form ```javascript // app/javascript/controllers/stay_dates_controller.js import { Controller } from "@hotwired/stimulus" import flatpickr from "flatpickr" export default class extends Controller { connect() { this.picker = flatpickr(this.element, { mode: "range" }) } disconnect() { this.picker.destroy() } } ``` Because the generated `config/importmap.rb` already has `pin_all_from "app/javascript/controllers", under: "controllers"`, the new controller needs no pin of its own; `flatpickr` resolves through the new vendored pin. ## The parts it does not handle | Need | importmap-rails | What you do | |---|---|---| | The package's JavaScript | vendored and pinned | nothing more | | The package's CSS | not fetched | download the stylesheet into a load-path folder such as `vendor/assets/stylesheets` and link it with `stylesheet_link_tag` | | A package that only ships CommonJS or needs a build | depends on what the CDN can serve as ESM | consider jsbundling-rails | | Removing it | `bin/importmap unpin flatpickr` | deletes the vendored file and the pin line | ## Options worth knowing - `--from unpkg` or `--from jsdelivr` downloads from that CDN instead of JSPM's; the file still lands in `vendor/javascript`. - `--preload false` or `--preload booking` writes `preload: false` or `preload: "booking"` on the pin, so the picker is not preloaded on every page. - `bin/importmap pristine` re-downloads every pinned package at its recorded version, useful when `vendor/javascript` was lost or edited by hand. ## Integrity hashes Calling `enable_integrity!` at the top of `config/importmap.rb` makes the rendered map carry an `integrity` entry for every pin whose `integrity:` option is `true` (the default). With Propshaft it also needs `config.assets.integrity_hash_algorithm`; without that, no hashes appear. ## Mistakes interviewers listen for - **Treating the CDN as a runtime dependency.** The resolver is used once, on the developer's machine; production serves the vendored copy. An outage at JSPM blocks new pins, not page loads. - **Ignoring dependency files.** A package that imports others arrives as several files in `vendor/javascript`, each with its own pin. Deleting one by hand breaks the package in the browser; `unpin` or `pristine` keeps the set consistent. - **Editing a vendored file in place.** The next `bin/importmap update` or `pristine` overwrites the edit without warning. A local patch belongs in a separate module that wraps the package. - **Deleting the version comment.** It looks like noise, but without it `bin/importmap outdated` and `audit` print that they are ignoring the package, so it silently leaves the security check.

  • Is a pin pointing at a CDN URL with to: still allowed in importmap-rails 2.2?
    Yes. `pin "name", to: "https://..."` works because `path_to_asset` returns full URLs unchanged, so the browser fetches from that CDN at runtime. `bin/importmap pin` no longer writes that form: it vendors the file, so the app serves it and does not depend on the CDN being up.
  • How do you add Subresource Integrity hashes to an importmap-rails map?
    Call `enable_integrity!` in `config/importmap.rb`; each `pin` and `pin_all_from` already defaults to `integrity: true`, and an explicit hash string or `integrity: false` overrides it per pin. With Propshaft you must also set `config.assets.integrity_hash_algorithm`, or no hashes are produced. The map then gains an `integrity` section and preload links carry the hash.

  • bin/importmap pin installs the package into node_modules through npm
  • The pin line keeps the browser loading the package from ga.jspm.io in production
  • vendor/javascript is generated at deploy time, so it belongs in .gitignore
  • bin/importmap pin also downloads the package's CSS and links it
  • The trailing # @version comment is optional decoration with no effect

Assumes Rails 8.1 with importmap-rails 2.2, where bin/importmap pin always downloads into vendor/javascript; tutorials showing pins to CDN URLs show a style the command no longer writes.

open as a page

In a Rails 8.1 app on importmap-rails, how do config/importmap.rb and javascript_importmap_tags let the browser run import statements with no Node build step?

level: juniorimportance: must knowfreq 58%

basics

~20 s

config/importmap.rb pins bare module names to files on the asset load path; javascript_importmap_tags renders those pins as a script type="importmap" block of digested URLs, adds modulepreload links and imports "application", so the browser resolves every import natively.

open as a page

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?

level: middleimportance: should knowfreq 28%

basics

~20 s

outdated 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.

open as a page

In importmap-rails, what does the preload: option on pin and pin_all_from control, what is its default, and when would you change it?

level: middleimportance: should knowfreq 36%

basics

~20 s

preload: decides whether javascript_importmap_tags emits a modulepreload link for a pin. It defaults to true, preloading every pin on every page; false defers a module until imported; an entry-point name preloads it only for that entry point.

open as a page

When does importmap-rails stop fitting a Rails 8.1 app, for instance once the team wants TypeScript, JSX or packages that only ship CommonJS, and what signals tell you to switch to a bundler?

level: seniorimportance: should knowfreq 34%

basics

~20 s

importmap-rails serves files exactly as written, so it fits only code the browser can run directly: plain ES modules and packages with browser ESM builds. TypeScript, JSX, CommonJS-only packages, CSS imported from JavaScript or a need for tree-shaking point to jsbundling-rails.

open as a page