How to use Import Maps in Rails 7 (with examples)

For almost 20 years now, Rails has been a synonym for effectiveness and excellent results, which is why we haven't hesitated to call it the perfect ally for startups. One reason Rails has stood the test of time is sheer boldness. Again and again, devs have shown they don't shy away from undertaking radical changes to give developers better tools.

Import Maps is a new feature on Rails 7 that allows us to load third-party javascript libraries in a default way by simply referencing those libraries to their bare module specifiers. This means we can now get rid of Webpack and Node.js from our package. We can still manage our JavaScript libraries, but our application will now manage multiple small ones instead of one big file. With Import Maps, we can finally use the libraries we want without wasting time with configuration.

Today we will walk you through different ways to use Import Maps, with real libraries and examples. Consider that while it works great to import js, Import Maps is not so straightforward when the library includes css code. Let's begin by taking a look at the easier case.

 

Import Maps for libraries without css

As said before, Import Maps is easy-peasy when used in libraries without css. JSPM -shortcut for JavaScript Package Management- is a tool that allows us to load a fully optimized NPM package inside the browser without any need for additional tooling. JSPM is used by Rails when serving JavaScript libraries in an application. 

If you want to install a library using a JSPM CDN you simply need the pin command and the library name. Run:

./bin/importmap pin feather-icons@4.28.0

 

Consider that there will be some specific cases in which you will have to use a different CDN. For example, for chart.js you can run:

./bin/importmap pin chart.js@2.9.4 --from jsdelivr

 

And that's it. As you can see, it's quite as simple as promised! 

Now let's move on to the slightly more challenging case of using Import Maps in libraries with css.

 

Import Maps for libraries with css 

When importing these types of libraries, you can choose one of the following paths:

 

Path 1: Import by using a gem. 

To exemplify with a step by step guide, we will use bootstrap:

 

Step 1:

Add to your gemfile: 

gem 'bootstrap', '~> 5.1.3'

 

And then run bundle install.

Step 2: 

Add boostrap to app/assets/stylesheets/application.scss:

// Bootstrap
@import "bootstrap";

Step 3: 

In config/initializers/assets.rb add:

Rails.application.config.assets.precompile += %w(bootstrap.min.js popper.js)

 

Step 4: 

In config/importmap.rb add:

pin "popper", to: 'popper.js', preload: true
pin "bootstrap", to: 'bootstrap.min.js', preload: true

Step 5: 

Lastly, in app/javascript/application.js:

import "popper"
import "bootstrap"

And that would be all. However, keep in mind the words of the Immortal Bard: All that glitters is not gold. Since not all gems are updated, this means that if, for example, you are trying to use a gem for the “simplebar” library, you will find that the only gem available has no stars and is not actively maintained. 

Path 2 : Download css and js files into your vendor folder. 

In this case, we will use simplebar for our example

Step 1:

First, download simplebar js file from: https://ga.jspm.io/npm:simplebar@5.3.6/dist/simplebar.esm.js 

Then copy it to vendor/javascript/simplebar.js

After this, download also css file from: https://ga.jspm.io/npm:simplebar@5.3.6/dist/simplebar.css 

Then copy it to vendor/stylesheets/simplebar.css. (Note: you may need to create vendor/stylesheet folder.)

Step 2:

Now, add vendor stylesheet to the assets paths, and add to config/initializers/assets.rb the line below:

Rails.application.config.assets.paths << Rails.root.join("vendor", "stylesheets")

Step 3: 

To pin simplebar., add the line below to config/importmap.rb:

pin "simplebar", to: "simplebar.js"

Step 4: 

Add simplebar to app/assets/stylesheets/application.scss:

@import "simplebar";

 

In case you don't mind maintaining your libraries manually, we firmly recommend you use this second option. 

 

Keep up the great coding!

 

We hope this guide will become a useful and handy tool whenever you want to use Import Maps to load JS libraries in your web application. As we said at the beginning, this will allow you to avoid big bundled files and instead serve multiple smaller files, with the advantage of easier cache and control. 

If you want to find more guides and tips for developers, as well as other interesting articles for entrepreneurs, keep browsing our blog.