Installation using Importmaps

In Rails 7+, Hotwire is configured by default using import maps. This guide will walk you through the files, gems, and configurations essential for this setup, ensuring a smooth integration right out of the box. Further information on Import maps can also be found on Rails Guides, Working with Javascript in Rails.

Setup

1. Creating a New Rails Project:

Begin by running the rails new command to generate a fresh Rails project. Once installed, delve into the Gemfile. This file includes several gems crucial for bundling the necessary dependencies for an import maps and Hotwire configuration. They include:

 # Use JavaScript with ESM import maps
 # [https://github.com/rails/importmap-rails]
 gem "importmap-rails"

 # Hotwire's SPA-like page accelerator
 # [https://turbo.hotwired.dev]
 gem "turbo-rails"

 # Hotwire's modest JavaScript framework
 # [https://stimulus.hotwired.dev]
 gem "stimulus-rails"

After executing bundle install, run rails importmap:install to integrate the required configurations and files into your project.

$ rails importmap:install
      apply  /path_to/gems/importmap-rails-1.2.3/lib/install/install.rb
  Add Importmap include tags in application layout
      insert    app/views/layouts/application.html.erb
  Create application.js module as entrypoint
      create    app/javascript/application.js
  Use vendor/javascript for downloaded pins
      create    vendor/javascript
      create    vendor/javascript/.keep
  Ensure JavaScript files are in the Sprocket manifest
      append    app/assets/config/manifest.js
  Configure importmap paths in config/importmap.rb
      create    config/importmap.rb
  Copying binstub
      create    bin/importmap
         run  bundle install

2. javascript_importmap_tags

The installation command will automatically modify your application.html.erb file by adding the <%= javascript_importmap_tags %> ERB tag. The <script> tags inserted in your page header will correspond to the configurations in config/importmap.rb.

3. Pinning Imports

Think of your import map in Rails as analogous to a package.json file in an NPM package. It’s where you declare (or “pin”) your app’s local and remote JS module dependencies. Use config/importmap.rb for this purpose.

Pins can be added manually or with the bin/importmap pin DEP_NAME command. For instance, to pin the lodash library:

$ bin/importmap pin lodash
Pinning "lodash" to https://ga.jspm.io/npm:lodash@4.17.21/lodash.js

This command updates config/importmap.rb:

pin "lodash", to: "https://ga.jspm.io/npm:lodash@4.17.21/lodash.js"

To remove a pin, either delete its entry in config/importmap.rb or use bin/importmap unpin DEP_NAME. Remember to restart your development server after any changes.

4. Importing Pins

Post-pinning, you can import a module into app/javascript/application.js or other scripts:

import _ from 'lodash';

5. Importing Turbo

Finally, import Turbo into your app/javascript/application.js:

import "@hotwired/turbo-rails"

This makes the Turbo instance globally accessible via window.Turbo.

Conclusion

This guide provides a basic overview of setting up import maps in Rails 7. Each component discussed offers its own set of configurable options, allowing you to tailor the setup to your application’s specific needs.