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!
Top comments (0)