DEV Community: Dipen Chauhan

Embracing New Asset Management in Rails 7.1: Switching to importmap-rails and dartsass-rails

Dipen Chauhan — Sun, 28 Jan 2024 00:41:20 +0000

Using importmap-rails and dartsass-rails instead of jsbundling-rails and cssbundling-rails in Rails 7.1

In the dynamic landscape of Rails development, selecting the most efficient and practical tools for JavaScript and CSS management is key. While Rails 7.1 continues to support traditional approaches like jsbundling-rails and cssbundling-rails, the Rails community has been exploring compelling alternatives. Among these are importmap-rails and dartsass-rails, which offer a more streamlined and modern asset management strategy. This guide will show you how to migrate from the conventional bundling tools to these newer options, enhancing your Rails 7.1 application's asset handling.

Prerequisites

Before diving into this guide, make sure you're familiar with the basics of Rails, Ruby, JavaScript, and CSS.

Why Choose importmap-rails and dartsass-rails?

importmap-rails and dartsass-rails offer several benefits over their predecessors:

Simplified project setup with fewer dependencies
Enhanced performance due to more efficient asset handling
Reduction in external tooling reliance, like Node.js and Yarn

Step-by-Step Migration Guide

1. Update Your Gemfile

Remove the old gems and add the new ones:

# Remove these
gem 'jsbundling-rails'
gem 'cssbundling-rails'

# Add these
gem 'turbo-rails'
gem 'importmap-rails'
gem 'dartsass-rails'

2. Install the New Gems

Run these commands to install and set up the new gems:

bundle install
./bin/rails importmap:install
./bin/rails dartsass:install

3. Configure Your Procfile.dev

Replace the yarn build commands with the appropriate Dartsass command:

css: bin/rails dartsass:watch

4. Customize Dartsass Configuration

Create a new file config/initializers/dartsass.rb with the following content to customize the CSS build process:

Rails.application.config.dartsass.builds = {
  "application.scss" => "application.css"
}
Rails.application.config.dartsass.build_options = " --style=expanded"

This configuration prefers expanded CSS for better readability and includes source maps.

5. Update application.html.erb

Ensure you have replaced javascript_include_tag "application" with <%= javascript_importmap_tags %>.

Configuring Import Maps and Dartsass

1. Default Manifest Setup

Your app/assets/config/manifest.js should look like this:

//= link_tree ../images
//= link_tree ../../javascript .js
//= link_tree ../../../vendor/javascript .js
//= link_tree ../builds

2. Import Map Configuration

Set up your config/importmap.rb to manage JavaScript dependencies:

pin "application"
pin "@hotwired/turbo-rails", to: "turbo.min.js", preload: true
pin "@hotwired/stimulus", to: "stimulus.min.js"
pin "@hotwired/stimulus-loading", to: "stimulus-loading.js"
pin_all_from "app/javascript/controllers", under: "controllers"

3. Imports in application.js File

Organize your JavaScript imports in app/javascript/application.js:

import "@hotwired/turbo-rails";
import "controllers";

4. Stimulus Controller Management

Opt for lazy loading in app/javascript/controllers/index.js to improve performance:

import { application } from "controllers/application";
import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
lazyLoadControllersFrom("controllers", application)

Adding External Libraries

1. Importing Libraries

Example: Adding moment-timezone.js:

./bin/importmap pin moment-timezone

This command downloads and saves 2 files:

https://ga.jspm.io/npm:moment-timezone@0.5.44/index.js to vendor/javascript/moment-timezone.js
https://ga.jspm.io/npm:moment@2.30.1/moment.js to vendor/javascript/moment.js

The command also updates config/importmap.rb:

pin "moment-timezone" # @0.5.44
pin "moment" # @2.30.1

Now you can import from your .js file:

import moment from "moment-timezone"

2. Handling Custom JavaScript Files

Example: Including 2 custom JS files located at

vendor/folder/subfolder/js1/hi.js and vendor/folder/subfolder/js2/hello.js

Update config/initializers/assets.rb:

Rails.application.config.assets.paths << 
Rails.root.join("vendor/folder/subfolder")

Modify app/assets/config/manifest.js:

//= link_tree ../../../vendor/folder/subfolder

Add entries to config/importmap.rb:

pin "hi", to: "js1/hi.js"
pin "hello", to: "js2/hello.js"

Import them in your JavaScript files:

import "hi";
import "hello";

Conclusion

After you are done adding all external libraries using pin in importmap.rb, you can delete the unused package.json file and node_modules folder.

Switching to importmap-rails and dartsass-rails in Rails 7.1 offers a more efficient and streamlined way to manage your JavaScript and CSS. This guide should help you make the transition smoothly. Feel free to share your experiences, ask questions, or provide feedback in the comments below.

Happy coding!

Add Bootstrap 5 and Font Awesome 6 to Rails 7

Dipen Chauhan — Wed, 03 Aug 2022 17:08:00 +0000

There is an easy way to add Bootstrap while creating an app using the Rails Command Line but here I have shown how to add them manually. In addition to adding Bootstrap 5 and Font Awesome 6 to our Rails 7 app, we will be adding JQuery, custom scss (custom.scss) and custom javascript (my_script.js) to the Rails 7 app.

Version

ruby 3.1.2
Rails 7.0.3.1
Bootstrap 5.2.0
Font Awesome 6.1.2

Instructions

In the Gemfile add:

gem "sassc-rails"
gem "bootstrap", "~> 5.2.0"
gem "jquery-rails"

Remember to bundle install in terminal before proceeding.

In terminal, (1) add Font Awesome, (2) Rename application.css to application.scss, (3) create custom.scss (4) create my_script.js:

$ bin/importmap pin @fortawesome/fontawesome-free
$ mv app/assets/stylesheets/application.css app/assets/stylesheets/application.scss
$ touch app/assets/stylesheets/custom.scss
$ touch app/javascript/my_script.js

Remove all the *= require and *= require_tree statements from application.scss

In app/assets/stylesheets/application.scss import bootstrap and custom.scss:

// Custom bootstrap variables must be set or imported *before* bootstrap.
@import "bootstrap";
@import "custom";

Enable Inline Source Maps in config/environments/development.rb:

config.sass.inline_source_maps = true

To properly enable it, clear your asset cache and restart the rails server:

$ rm -r tmp/cache/assets

In config/importmap.rb:

# From "jquery-rails" gem
pin "jquery", to: "jquery3.min.js", preload: true
pin "jquery_ujs", to: "jquery_ujs.js", preload: true

# From "bootstrap" gem
pin "bootstrap", to: "bootstrap.min.js", preload: true
pin "@popperjs/core", to: "popper.js", preload: true

# Use all.js instead of fontawesome.js
pin "@fortawesome/fontawesome-free", to: "https://ga.jspm.io/npm:@fortawesome/fontawesome-free@6.1.2/js/all.js"

# Custom JS
pin "my_script", to: "my_script.js", preload: true

In config/initializers/assets.rb (add js files that came with the gem):

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

In application.js:

import "jquery";
import "jquery_ujs";
import "@popperjs/core";
import "bootstrap";
import "@fortawesome/fontawesome-free";
import "my_script";

In custom.scss:

body {
  background-color: #888;
}

In my_script.js:

// Test if jquery is loaded by typing $.fn.jquery in the console as per
// https://stackoverflow.com/questions/6973941/how-to-check-what-version-of-jquery-is-loaded/26674265#26674265

// This function runs on every page "load"
document.addEventListener("turbo:load", () => {
  const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]');
  const popoverList = [...popoverTriggerList].map((popoverTriggerEl) => new bootstrap.Popover(popoverTriggerEl));
});

Important Note

The only time you need to add to config.assets.precompile in assets.rb is when you want to add JavaScript from a gem. In other words when using ./bin/importmap pin command to add JavaScript files, you do not need to add anything in assets.rb
Any time you have a custom JavaScript file, you have to include it in importmap.rb. For e.g. add line: pin "my_script", to: "my_script.js", preload: true to importmap.rb and add line import "my_script.js" to application.js. If you add custom JavaScript files in your application.js file and not in importmap.rb, your app may function in development mode but in production mode your JavaScript files will not get loaded.

Testing to see if Bootstrap and JS work as expected

Create home controller with index action

$ rails g controller home index

Add Bootstrap modal component in app/views/home/index.html.erb:

<div class="container">
  <div class="row">
    <div class="col-md-4 mt-4">

      <i class="fa-solid fa-house fa-2xl mx-3"></i>
      <i class="fa-solid fa-plane fa-2xl mx-3"></i>
      <i class="fa-solid fa-martini-glass fa-2xl mx-3"></i>

    </div>
    <div class="col-md-8 mt-4">
      <button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" data-bs-title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>
    </div>
  </div>

  <div class="row mt-4">
    <div class="col-md-8">
      <button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
        Popover on top
      </button>
      <button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Right popover">
        Popover on right
      </button>
      <button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Bottom popover">
        Popover on bottom
      </button>
      <button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Left popover">
        Popover on left
      </button>
    </div>
  </div>
</div>

Go to http://localhost:3000. You should see popovers by clicking any button (Bootstrap and my_script.js in action). The background must be grey (set by custom.scss). You must see 3 icons: Home, Plane and Martini. Open up the web browser console and type:

$.fn.jquery

It should return the version of jQuery which is 3.6.0 at the time of writing this document.

Link to example app: https://github.com/overdrivemachines/bootstrap-rails7