Import maps (Rails 7+)

Introduction

Import maps let you use JavaScript modules in Rails without needing extra build tools. They help your app load JavaScript files directly in the browser.

You want to add JavaScript to a Rails app without setting up Webpack or other bundlers.

You want to keep your app simple and avoid complex JavaScript build steps.

You want to load JavaScript modules from CDNs or local files easily.

You want to quickly prototype JavaScript features in Rails.

You want to manage JavaScript dependencies declaratively in Rails.

Syntax

Ruby on Rails

importmap pin "module-name" [to: "url-or-path"]

// In your JavaScript file:
import { something } from "module-name"

// In your Rails layout:
<%= javascript_importmap_tags %>

The importmap pin command registers a JavaScript module with a name and optional URL or path.

Use javascript_importmap_tags helper in your layout to load the import map and modules.

Examples

This pins a local module named "application" and an external module "lodash" from a CDN.

Ruby on Rails

importmap pin "application"
importmap pin "lodash", to: "https://cdn.skypack.dev/lodash"

Imports the debounce function from the pinned "lodash" module and uses it.

Ruby on Rails

// In app/javascript/application.js
import { debounce } from "lodash"
debounce(() => console.log('Hello'), 300)

This Rails helper inserts the necessary script tags to load the import map and modules in your HTML.

Ruby on Rails

<%= javascript_importmap_tags %>

Sample Program

This example shows how to pin modules in importmap.rb, import and use a function from lodash in application.js, and include the import map tags in the Rails layout. When you click the button, it alerts "Clicked!" with a debounce delay.

Ruby on Rails

// config/importmap.rb
importmap pin "application"
importmap pin "lodash", to: "https://cdn.skypack.dev/lodash"

// app/javascript/application.js
import { debounce } from "lodash"
window.onload = () => {
  const button = document.getElementById('btn')
  button.addEventListener('click', debounce(() => alert('Clicked!'), 500))
}

// app/views/layouts/application.html.erb
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Importmap Demo</title>
  <%= javascript_importmap_tags %>
</head>
<body>
  <button id="btn">Click me</button>
</body>
</html>

Important Notes

Import maps work best for small to medium JavaScript needs without complex bundling.

You can update pinned modules by running bin/importmap pin commands.

Remember to restart your Rails server after changing importmap configuration.

Summary

Import maps let Rails apps load JavaScript modules without bundlers.

Use importmap pin to register modules and javascript_importmap_tags to load them.

This keeps JavaScript simple and easy to manage in Rails 7+.

Practice

1. What is the main purpose of using importmap in Rails 7+?

easy

A. To load JavaScript modules without needing a bundler

B. To compile Ruby code into JavaScript

C. To manage database migrations automatically

D. To style HTML elements with CSS

Solution

1. Step 1: Understand importmap's role in Rails 7+

   Import maps allow Rails apps to load JavaScript modules directly in the browser without bundling tools.

2. Step 2: Compare other options

   Options B, C, and D describe unrelated tasks: compiling Ruby, managing migrations, and styling, which are not importmap's purpose.

3. Final Answer:

   To load JavaScript modules without needing a bundler -> Option A

4. Quick Check:

   Import maps = load JS modules without bundler [OK]

Hint: Import maps = JS modules without bundler [OK]

Common Mistakes:

• Confusing importmap with asset bundlers
• Thinking importmap compiles Ruby code
• Mixing importmap with CSS or database tasks

2. Which command correctly registers a JavaScript module named chart.js using importmap in Rails?

easy

A. rails importmap add chart.js

B. bin/importmap pin chart.js

C. rails importmap pin chart.js

D. importmap pin chart.js

Solution

1. Step 1: Identify the correct command syntax

   The correct command to pin a module in Rails 7+ is bin/importmap pin [module].

2. Step 2: Check other options

   Options B, C, and D are incorrect: B uses an incorrect verb add, C uses invalid rails importmap pin, and D misses the bin/ prefix.

3. Final Answer:

   bin/importmap pin chart.js -> Option B

4. Quick Check:

   Pin module command = bin/importmap pin [name] [OK]

Hint: Use 'bin/importmap pin' to register modules [OK]

Common Mistakes:

• Using 'rails importmap' instead of 'bin/importmap'
• Using 'add' instead of 'pin'
• Omitting 'bin/' prefix in the command

3. Given this Rails view code snippet:

<%= javascript_importmap_tags %>

What does this helper do in a Rails 7+ app using import maps?

medium

A. It generates CSS styles for JavaScript components

B. It compiles JavaScript files into one bundle

C. It removes unused JavaScript from the app

D. It loads all pinned JavaScript modules into the HTML page

Solution

1. Step 1: Understand the helper's purpose

   javascript_importmap_tags inserts script tags to load all pinned JS modules via import maps in the HTML.

2. Step 2: Eliminate incorrect options

   It does not bundle, remove unused code, or generate CSS styles.

3. Final Answer:

   It loads all pinned JavaScript modules into the HTML page -> Option D

4. Quick Check:

   javascript_importmap_tags = load pinned JS modules [OK]

Hint: javascript_importmap_tags loads pinned JS modules [OK]

Common Mistakes:

• Thinking it bundles JS files
• Assuming it cleans unused code
• Confusing it with CSS helpers

4. You run rails importmap pin my_module but your JavaScript module does not load in the browser. What is the most likely mistake?

medium

A. You forgot to add <%= javascript_importmap_tags %> in your layout

B. You used pin instead of add command

C. You need to restart the Rails server after pinning

D. You must compile assets with webpack first

Solution

1. Step 1: Check how import maps load modules

   Pinning registers the module, but javascript_importmap_tags must be in the layout to load scripts.

2. Step 2: Review other options

   You used pin instead of add command is incorrect because pin is the right command. You need to restart the Rails server after pinning is unnecessary; no restart needed. You must compile assets with webpack first is wrong because import maps do not require webpack.

3. Final Answer:

   You forgot to add <%= javascript_importmap_tags %> in your layout -> Option A

4. Quick Check:

   Missing javascript_importmap_tags = no JS load [OK]

Hint: Add javascript_importmap_tags in layout to load modules [OK]

Common Mistakes:

• Not including javascript_importmap_tags in views
• Confusing pin with add command
• Thinking server restart is required
• Assuming webpack is needed with import maps

5. You want to use a third-party JavaScript library hosted on a CDN with import maps in Rails 7+. Which is the correct way to pin it in config/importmap.rb?

hard

A. pin 'library', from: 'https://cdn.example.com/library.js'

B. pin 'library', to: '/assets/library.js'

C. pin 'library', to: 'https://cdn.example.com/library.js'

D. pin 'library', url: 'https://cdn.example.com/library.js'

Solution

1. Step 1: Understand pin syntax for external URLs

   To pin a module from a CDN, use pin 'name', to: 'URL' in config/importmap.rb.

2. Step 2: Check other options

   pin 'library', to: '/assets/library.js' uses a local path, not CDN. Options C and D use incorrect keys from and url which are invalid.

3. Final Answer:

   pin 'library', to: 'https://cdn.example.com/library.js' -> Option C

4. Quick Check:

   Pin CDN module = pin 'name', to: 'URL' [OK]

Hint: Use 'to:' with CDN URL when pinning external modules [OK]

Common Mistakes:

• Using wrong keys like 'from' or 'url'
• Pinning local path instead of CDN URL
• Confusing syntax for pinning external scripts