Getting started

Installation

One Gemfile line. An app already on importmap-rails needs nothing else.

Requirements#

Requirement	Version
`Ruby`	>= 3.1
`Rails`	>= 6.0 (Rails 7.0+ for the ESM builds of Action Cable, Action Text and Active Storage)
Asset pipeline	Propshaft or Sprockets
Minifier	optional — bun, esbuild or terser for `--minify`

Replace importmap-rails#

Rails 7+ ships importmap-rails for new applications; swap it.

Replace gem "importmap-rails" with gem "importmap-plus" in your Gemfile and run bundle install:

Gemfile

gem "importmap-plus"

That is the whole migration for an app already on importmap-rails: the pins, config/importmap.rb, the helpers and the Importmap:: constants are unchanged, and the vendored files in vendor/javascript keep working. The first bin/importmap command you run may rewrite a pin comment to record where a package came from — see Provenance.

An app without an import map#

Install, then run the generator.

./bin/bundle add importmap-plus
./bin/rails importmap:install

The installer:

adds <%= javascript_importmap_tags %> to app/views/layouts/application.html.erb,
creates app/javascript/application.js as the entrypoint,
creates vendor/javascript for downloaded pins,
links both directories in the Sprockets manifest when the app uses Sprockets,
copies config/importmap.rb and the bin/importmap binstub.

JavaScript from Rails frameworks#

To use JavaScript from Action Cable, Action Text and Active Storage you must be on Rails 7.0+, the first version that shipped ESM-compatible builds of those libraries. Pin them to the compiled versions included in Rails:

config/importmap.rb

pin "@rails/actioncable", to: "actioncable.esm.js"
pin "@rails/activestorage", to: "activestorage.esm.js"
pin "@rails/actiontext", to: "actiontext.esm.js"
pin "trix"