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?
answer
- JSPM generator resolves the package
- downloads into vendor/javascript
- pin line with a # @version comment
- --from unpkg or jsdelivr
- JavaScript only; CSS is on you
basics
~20 sbin/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 linesbin/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 flatpickrgo deeper
Recall that bin/importmap pin downloads into vendor/javascript and appends a pin line, and that both are committed.
Explain the JSPM resolution, dependency files, the version comment, the --from and --preload options, and that CSS is not part of it.
Show judgement about vendoring: no runtime CDN dependency, reviewable diffs of third-party code, SRI via enable_integrity!, and pristine for recovery.
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.