Leaflet + Rails 7 quick start guide

The new version of Ruby on Rails comes with Import Maps as the default way to manage assets such as JavaScript and CSS. Although this article explains very well how the new asset pipeline works, I struggled a bit when trying to set up a simple map using the Leaflet library.

This article summarizes the steps I followed to make it work. It assumes that you have a basic Rails 7 app up and running, with no changes in the asset pipeline (this means no Webpacker nor any other custom bundler).

Step 1: Pin the libraries in Import Map

From the root directory of your project, add leaflet to your import map with the following command:

./bin/importmap pin leaflet

I want to use the Humanitarian OpenStreetMap, so I also added the leaflet-providers library:

./bin/importmap pin leaflet-providers

You can add any other Leaflet plugin using this method.

This will automatically pin the libraries in your config/importmap.rb, and map them to the provided directions, like this:

# config/importmap.rb
pin “leaflet”, to: “https://ga.jspm.io/npm:leaflet@1.7.1/dist/leaflet-src.js"
pin “leaflet-providers”, to: “https://ga.jspm.io/npm:leaflet-providers@1.13.0/leaflet-providers.js"

As you can see, these are npm packages that are now available in my app through the import map, without the need of a package.json. Awesome!

Step 2: Import the libraries

Now that the packages are available, you have to actually import them. Add the following lines to your application.js:

// app/javascript/application.js
import “leaflet”
import “leaflet-providers”

If you pinned other plugins in the previous step, you have to import them as well.

Step 3: Add the CSS

We have our JavaScript loaded now, but we’re still missing the CSS files. I just followed the instructions provided in the Leaflet Quick Start Guide and added the following stylesheet link to my application layout:

/ app/views/layouts/application.html.slim
= stylesheet_link_tag "https://unpkg.com/leaflet@1.7.1/dist/leaflet.css", integrity: "sha512-xodZBNTC5n17Xt2atTPuE1HxjVMSvLVW9ocqUKLsCC5CXdbqCmblAshOMAS6/keqq/sMZMZ19scR4PsZChSR7A==", crossorigin: ""

The CSS must be loaded before the JS, so this tag must be placed above the javascript_importmap_tags in your application layout.

Step 4

Now you’re ready to follow the Leaflet Quick Start Guide starting from the third step. Note that any JavaScript you write to initialize and customize your map should be also imported in order to work.

Since Rails 7 comes with Stimulus by default, I took advantage of this and created a controller to encapsulate the logic for my map:

// app/javascript/controllers/map_controller.js
import { Controller } from "@hotwired/stimulus"
import L from 'leaflet'
export default class extends Controller {
  // Map logic goes here
}

Then you just have to pass the controller to the div that contains your map in the view:

/ app/views/your-model/your-view.html.slim
#map data-controller=”map”

That’s it! Happy mapping :-)