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](https://bun.sh), [esbuild](https://esbuild.github.io) or [terser](https://terser.org) 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`:

```ruby
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](https://importmap-plus.zoolutions.llc/docs/provenance).

## An app without an import map

Install, then run the generator.

```shell
./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:

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