Ror Asset Pipeline

title: Ruby on Rails Asset Pipeline — Complete Guide to CSS, JS, and Images description: 'Learn Ruby on Rails asset pipeline: Import Maps, Sprockets, Propshaft, CSS bundling, JavaScript bundling, image optimization, and asset precompilation for production.' date: 2026-06-28 lastmod: 2026-06-28 weight: 27 tags: [backend, ror]

Rails asset pipeline manages CSS, JavaScript, and image assets through Import Maps (Rails 7+) for JavaScript, Sprockets/Propshaft for CSS, and precompilation for production deployment.

## What You'll Learn

By the end of this tutorial, you'll configure Import Maps for JavaScript, use Propshaft for CSS, add Bootstrap via CSS bundling, optimize images, and precompile assets for production.

## Real-World Use

A Rails 8 app uses Import Maps to load JavaScript libraries directly from CDN without Webpack/Node. Bootstrap is bundled via cssbundling-rails. Assets precompile to fingerprinted files in production.

## Asset Pipeline Learning Path

```mermaid
flowchart LR
  A[Testing] --> B[Asset Pipeline]
  B --> C[Mailers]
  C --> D[Background Jobs]
  D --> E[Caching]
  B --> F{You Are Here}
  style F fill:#f90,color:#fff

Import Maps

# Gemfile (Rails 7+ default)
gem "importmap-rails"

rails importmap:install

# config/importmap.rb
pin "application"
pin "@hotwired/turbo-rails", to: "turbo.min.js"
pin "@hotwired/stimulus", to: "stimulus.min.js"
pin "@hotwired/stimulus-loading", to: "stimulus-loading.js"
pin_all_from "app/javascript/controllers", under: "controllers"

# Pin from CDN
pin "chart.js", to: "https://ga.jspm.io/npm:chart.js@4.4.0/dist/chart.js"

// app/javascript/application.js
import "@hotwired/turbo-rails"
import "controllers"
import "chart.js"

CSS with Propshaft

# Gemfile
gem "propshaft"  # Rails 7+ default (replaces Sprockets)

/* app/assets/stylesheets/application.css */
 *= require_self
 *= require_tree .
 */

/* app/assets/stylesheets/custom.css */
body {
  font-family: system-ui, -apple-system, sans-serif;
  line-height: 1.5;
  margin: 0;
  padding: 0;
}
.container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 0 1rem;
}

CSS Bundling (Bootstrap)

rails css:install:bootstrap
# Installs Bootstrap via cssbundling-rails

// app/assets/stylesheets/application.bootstrap.scss
@import "bootstrap/scss/bootstrap";
@import "custom";

<!-- In layout -->
<%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
<%= javascript_importmap_tags %>

JavaScript (Webpack/Esbuild)

rails javascript:install:esbuild
# Alternative to Import Maps (needs Node.js)

// app/javascript/application.js
import "./controllers"
import "bootstrap"

// package.json
{
  "scripts": {
    "build": "esbuild app/javascript/*.* --bundle --sourcemap --outdir=app/assets/builds"
  }
}

Asset Precompilation

# Production precompilation
RAILS_ENV=production rails assets:precompile

# Check compiled assets
ls public/assets/
# application-1a2b3c4d5e.css, application-1a2b3c4d5e.js

# config/environments/production.rb
config.assets.compile = false  # Don't fall back to Sprockets
config.assets.digest = true    # Fingerprinted filenames

Common Mistakes

1. Not Precompiling in Production

Forgetting rails assets:precompile causes missing assets in production. Run as a deployment step.

2. Using Both Import Maps and Webpack

Choose one approach. Import Maps (Rails 7+) is simpler. Webpack/esbuild is for complex JS setups.

3. Not Clearing Cache After Changes

Old compiled assets remain. Run rails assets:clobber to clear, then recompile.

4. Loading Unused JavaScript

Large JavaScript bundles slow page loads. Pin only what you need with Import Maps.

5. Forgetting data-turbo-track

Missing data-turbo-track on stylesheet_link_tag causes Turbo not to reload CSS on navigation.

Practice Questions

1. What is Import Maps in Rails?

A way to manage JavaScript libraries without Webpack/Node. Libraries are pinned to URLs in config/importmap.rb.

2. What does propshaft do?

Propshaft is the asset pipeline for CSS and images. It compiles, fingerprints, and serves static assets.

3. How do you add Bootstrap to Rails?

Run rails css:install:bootstrap. It installs Bootstrap and configures the pipeline.

4. What is asset precompilation?

The process of compiling CSS, JS, and images into fingerprinted production files in public/assets/.

5. Challenge: Set up Import Maps for a Rails app and add a JavaScript library from CDN.

# config/importmap.rb
pin "application"
pin "alpinejs", to: "https://ga.jspm.io/npm:alpinejs@3.13.0/dist/cdn.js"

FAQ

Mini Project: Configure Assets

Set up Import Maps, add Bootstrap, and configure production precompilation.

rails importmap:install
rails css:install:bootstrap
# Add custom CSS
# Pin JS libraries in importmap.rb
RAILS_ENV=production rails assets:precompile

What's Next

Ruby on Rails Mailers Ruby on Rails Background Jobs