Propshaft vs Sprockets: Complete Rails 8 Asset Pipeline Migration Guide

# app/assets/config/manifest.js
//= link_tree ../images
//= link_directory ../stylesheets .css
//= link_tree ../../javascript .js
//= link_tree ../../../vendor/javascript .js

# config/initializers/assets.rb - Typical Sprockets configuration
Rails.application.config.assets.version = '1.0'
Rails.application.config.assets.precompile += %w( admin.js admin.css )
Rails.application.config.assets.precompile += %w( mobile/*.js mobile/*.css )
Rails.application.config.assets.paths << Rails.root.join('app', 'assets', 'fonts')
Rails.application.config.assets.paths << Rails.root.join('vendor', 'assets', 'javascripts')
Rails.application.config.assets.css_compressor = :sass
Rails.application.config.assets.js_compressor = :terser

# The entire Propshaft configuration for most applications
# config/application.rb
config.assets.pipeline = :propshaft

/* app/assets/stylesheets/application.css */
/* Propshaft doesn't process @import directives */
/* Instead, use link tags in your layout: */

# config/importmap.rb
pin "application", preload: true
pin "@hotwired/turbo-rails", to: "turbo.min.js", preload: true
pin "@hotwired/stimulus", to: "stimulus.min.js", preload: true
pin "@hotwired/stimulus-loading", to: "stimulus-loading.js", preload: true

# Pin local JavaScript modules
pin_all_from "app/javascript/controllers", under: "controllers"
pin_all_from "app/javascript/components", under: "components"

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

# app/models/user.rb
class User < ApplicationRecord
  has_one_attached :avatar do |attachable|
    attachable.variant :thumb, resize_to_limit: [100, 100]
  end
end

# Sprockets precompilation
$ time bin/rails assets:precompile
...
real    0m48.742s
user    0m42.315s
sys     0m6.427s

# Propshaft asset compilation
$ time bin/rails assets:precompile
...
real    0m4.128s
user    0m2.845s
sys     0m1.283s

# Memory profiling during asset compilation
require 'objspace'

# Sprockets compilation
ObjectSpace.memsize_of_all
# => 425MB peak memory usage

# Propshaft compilation
ObjectSpace.memsize_of_all
# => 87MB peak memory usage

// This won't compile in Propshaft
.button {
  $primary-color: #007bff;
  background: $primary-color;

  &:hover {
    background: darken($primary-color, 10%);
  }
}

# Gemfile
gem 'sassc-rails'  # Compile Sass outside Propshaft
gem 'tailwindcss-rails'  # Use Tailwind for utility-first CSS

# app/assets/javascripts/example.coffee
# Won't compile in Propshaft
class Example
  constructor: (@name) ->
    console.log "Hello, #{@name}"

// app/javascript/example.js
class Example {
  constructor(name) {
    this.name = name;
    console.log(`Hello, ${this.name}`);
  }
}

//= require jquery
//= require jquery_ujs
//= require_tree .

# lib/tasks/minify.rake
namespace :assets do
  desc "Minify JavaScript and CSS"
  task minify: :environment do
    require 'terser'
    # Custom minification logic
  end
end

# Audit your current Sprockets configuration
$ grep -r "assets" config/
$ find app/assets -type f | wc -l
$ cat app/assets/config/manifest.js

# lib/tasks/asset_audit.rake
namespace :assets do
  desc "Audit current asset configuration"
  task audit: :environment do
    puts "=== Asset Audit ==="
    puts "Sprockets version: #{Sprockets::VERSION}"
    puts "Asset paths: #{Rails.application.config.assets.paths}"
    puts "Precompiled assets: #{Rails.application.config.assets.precompile}"
    puts "\n=== File Inventory ==="

    asset_types = {
      javascript: Dir.glob("app/assets/javascripts/**/*.{js,coffee}").count,
      stylesheets: Dir.glob("app/assets/stylesheets/**/*.{css,scss,sass}").count,
      images: Dir.glob("app/assets/images/**/*").count
    }

    asset_types.each { |type, count| puts "#{type}: #{count} files" }
  end
end

# Find Sprockets directives
$ grep -r "//=" app/assets/javascripts/
$ grep -r "*=" app/assets/stylesheets/

# Find CoffeeScript files
$ find app/assets -name "*.coffee"

# Find Sass/SCSS files
$ find app/assets -name "*.scss" -o -name "*.sass"

# Check for ERB in assets
$ find app/assets -name "*.erb"

# Ensure you're on Rails 7.1 or higher with Sprockets
$ bundle update rails
$ rails -v  # Should show 7.1.x or higher

$ bin/rails importmap:install

# config/importmap.rb
pin "application", preload: true

// app/javascript/application.js
// Entry point for the build script in your package.json
console.log("Hello from application.js")

# Install conversion tool
$ npm install -g decaffeinate

# Convert all CoffeeScript files
$ find app/assets/javascripts -name "*.coffee" -exec decaffeinate {} \;

# Before: app/assets/javascripts/users.coffee
class User
  constructor: (@name, @email) ->

  greet: ->
    "Hello, #{@name}"

// After: app/javascript/users.js
class User {
  constructor(name, email) {
    this.name = name;
    this.email = email;
  }

  greet() {
    return `Hello, ${this.name}`;
  }
}

# Gemfile
gem 'sassc-rails'  # Sass compilation
gem 'dartsass-rails'  # Alternative: Dart Sass for modern features

# package.json (if using Dart Sass via npm)
{
  "scripts": {
    "build:css": "sass ./app/assets/stylesheets:./app/assets/builds --no-source-map --load-path=node_modules"
  }
}

# config/application.rb
config.dartsass.builds = {
  "application.scss" => "application.css"
}

# Gemfile
# Remove or comment out Sprockets
# gem 'sprockets-rails'

# Add Propshaft
gem 'propshaft'

$ bundle install

# config/application.rb
module YourApp
  class Application < Rails::Application
    # ...existing config...

    # Switch to Propshaft
    config.assets.pipeline = :propshaft
  end
end

# config/initializers/assets.rb
# DELETE these Sprockets-specific configurations:
# Rails.application.config.assets.version = '1.0'
# Rails.application.config.assets.precompile += %w( admin.js admin.css )
# Rails.application.config.assets.paths << ...
# Rails.application.config.assets.css_compressor = :sass
# Rails.application.config.assets.js_compressor = :terser

# Propshaft needs minimal configuration:
# (Usually nothing needed here)

$ mkdir -p app/javascript
$ mv app/assets/javascripts/* app/javascript/
$ rm -rf app/assets/javascripts

# Keep stylesheets in app/assets/stylesheets
# But remove Sprockets directives

/* app/assets/stylesheets/application.css */
/* BEFORE (Sprockets directives - remove these): */
/*
 *= require_tree .
 *= require_self
 */

/* AFTER (Plain CSS - or use link tags in layout): */
/* Global styles */

# config/importmap.rb
# Pin application entry point
pin "application", preload: true

# Pin JavaScript dependencies
pin "@hotwired/turbo-rails", to: "turbo.min.js", preload: true
pin "@hotwired/stimulus", to: "stimulus.min.js", preload: true

# Pin all controllers
pin_all_from "app/javascript/controllers", under: "controllers"

# Pin third-party libraries (from CDN or vendor)
pin "jquery", to: "https://cdn.jsdelivr.net/npm/jquery@3.7.1/dist/jquery.min.js"

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

# Precompile assets
$ RAILS_ENV=production bin/rails assets:precompile

# Check compiled assets
$ ls -lh public/assets/

# Verify digested filenames
$ ls public/assets/*.css
# application-abc123.css

# Test asset serving locally
$ RAILS_ENV=production bin/rails server
# Visit http://localhost:3000 and check browser console for asset errors

# rails console
> helper.asset_path("application.css")
=> "/assets/application-abc123.css"

> helper.image_path("logo.png")
=> "/assets/logo-def456.png"

> helper.javascript_importmap_tags
# Should return import map script tags

# Run system tests to verify asset loading
$ bin/rails test:system

# Check for missing asset errors in logs
$ grep "Asset.*not found" log/test.log

# Clean assets
$ bin/rails assets:clobber

# Benchmark Propshaft compilation
$ time RAILS_ENV=production bin/rails assets:precompile

# Ensure asset precompilation happens during deployment
# Capistrano example:

# config/deploy.rb
before 'deploy:assets:precompile', 'deploy:assets:clean'

namespace :deploy do
  namespace :assets do
    task :clean do
      on roles(:web) do
        within release_path do
          execute :rake, 'assets:clobber RAILS_ENV=production'
        end
      end
    end
  end
end

FROM ruby:3.4-alpine

# Install dependencies for asset compilation
RUN apk add --no-cache nodejs npm

WORKDIR /app

# Install gems
COPY Gemfile Gemfile.lock ./
RUN bundle install

# Copy application
COPY . .

# Precompile assets (much faster with Propshaft)
RUN RAILS_ENV=production SECRET_KEY_BASE=dummy bundle exec rails assets:precompile

EXPOSE 3000
CMD ["rails", "server", "-b", "0.0.0.0"]

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.4
          bundler-cache: true

      - name: Precompile assets
        run: |
          bundle exec rails assets:precompile
        env:
          RAILS_ENV: production
          SECRET_KEY_BASE: ${{ secrets.SECRET_KEY_BASE }}

      - name: Deploy
        run: |
          # Your deployment commands

# config/initializers/asset_monitoring.rb
Rails.application.configure do
  config.middleware.use(Rack::Attack) if Rails.env.production?

  # Monitor 404s on asset requests
  ActiveSupport::Notifications.subscribe('process_action.action_controller') do |name, start, finish, id, payload|
    if payload[:path]&.start_with?('/assets/') && payload[:status] == 404
      Rails.logger.error "Asset not found: #{payload[:path]}"
      # Send to monitoring service (e.g., Sentry, New Relic)
    end
  end
end

# Converted CoffeeScript to JavaScript
$ find app/assets/javascripts -name "*.coffee" | wc -l
87
$ decaffeinate app/assets/javascripts/**/*.coffee
# Manual review and cleanup of converted files

# Set up Dart Sass for preprocessing
$ bundle add dartsass-rails

# Switched to Propshaft
gem 'propshaft'
# Removed gem 'sprockets-rails'

# config/application.rb
config.assets.pipeline = :propshaft

# Restructured assets
$ mv app/assets/javascripts app/javascript

# Monitoring setup that caught 12 issues before production
# config/initializers/asset_monitoring.rb
Rails.application.configure do
  ActiveSupport::Notifications.subscribe('load.propshaft') do |name, start, finish, id, payload|
    if payload[:path].nil?
      Sentry.capture_message("Missing asset: #{payload[:logical_path]}")
    end
  end
end

# Shared asset gem approach
# shared_assets/shared_assets.gemspec
Gem::Specification.new do |spec|
  spec.name          = "shared_assets"
  spec.version       = "1.0.0"
  spec.files         = Dir["app/assets/**/*"]
  spec.add_dependency "propshaft"
end

# Each microservice's Gemfile
gem 'shared_assets', path: '../shared_assets'

# config/application.rb (in each service)
config.assets.paths << SharedAssets.asset_path

// Shared component with import map
// shared_assets/app/assets/javascripts/components/modal.js
export class Modal {
  constructor(element) {
    this.element = element;
    this.setupEventListeners();
  }

  setupEventListeners() {
    this.element.querySelector('.close').addEventListener('click', () => {
      this.close();
    });
  }

  open() {
    this.element.classList.add('active');
  }

  close() {
    this.element.classList.remove('active');
  }
}

// Each service's import map pins the shared component
// config/importmap.rb
pin "components/modal", to: "shared_assets/components/modal.js"

# Running Propshaft and Sprockets simultaneously during transition
# Gemfile
gem 'propshaft'
gem 'sprockets-rails'  # Keep temporarily for legacy assets

# config/application.rb
config.assets.pipeline = :propshaft

# config/environments/production.rb
# Serve legacy assets from separate path
config.assets.prefix = '/assets'

# Mount legacy Sprockets assets via Rack::Static
config.middleware.insert_before ActionDispatch::Static, Rack::Static,
  urls: ['/legacy-assets'], root: Rails.root.join('public')

# lib/asset_pipeline_feature_flag.rb
class AssetPipelineFeatureFlag
  def self.use_propshaft_for?(controller_name, action_name)
    # Gradual rollout based on traffic patterns
    migrated_routes = [
      {controller: "home", action: "index"},
      {controller: "products", action: "show"},
      {controller: "cart", action: "index"}
    ]

    migrated_routes.any? do |route|
      route[:controller] == controller_name &&
      route[:action] == action_name
    end
  end
end

# app/views/layouts/application.html.erb
<% if  AssetPipelineFeatureFlag.use_propshaft_for?(controller_name, action_name) %>
  <%= javascript_importmap_tags %>
<% else  %>
  <%= javascript_include_tag "application", "data-turbo-track": "reload" %>
<% end  %>

# 1. Verify asset exists in correct location
$ ls app/javascript/components/modal.js

# 2. Check import map configuration
# config/importmap.rb
pin "components/modal", to: "components/modal.js"

# 3. Precompile and verify
$ RAILS_ENV=production bin/rails assets:precompile
$ ls public/assets/components/modal-*.js

# 4. Check asset path in production
# config/environments/production.rb
config.assets.prefix = '/assets'  # Should match public/assets location

# lib/tasks/verify_assets.rake
namespace :assets do
  desc "Verify all assets are accessible"
  task verify: :environment do
    missing_assets = []

    # Check manifest.json exists
    manifest_path = Rails.root.join("public/assets/.manifest.json")
    unless File.exist?(manifest_path)
      puts "❌ Missing manifest.json - run rails assets:precompile first"
      exit 1
    end

    # Parse importmap.rb
    importmap_file = Rails.root.join("config/importmap.rb")
    importmap_content = File.read(importmap_file)

    # Extract pinned assets
    pins = importmap_content.scan(/pin\s+"([^"]+)"/)

    # Load manifest for digest lookup
    manifest = JSON.parse(File.read(manifest_path))

    pins.each do |pin_name|
      logical = pin_name[0]

      # Check manifest for digested version
      digested = manifest[logical] || manifest["#{logical}.js"]

      if digested
        # Verify digested file exists (handle both filename and full path)
        digested_basename = File.basename(digested)
        full_path = Rails.root.join("public/assets", digested_basename)

        # Also check with glob for digest variations
        glob_pattern = Rails.root.join("public/assets/#{logical.sub('.js', '')}-*.js")
        glob_matches = Dir.glob(glob_pattern)

        unless File.exist?(full_path) || glob_matches.any?
          missing_assets << logical
        end
      else
        missing_assets << logical
      end
    end

    if missing_assets.any?
      puts "❌ Missing assets:"
      missing_assets.each { |asset| puts "  - #{asset}" }
      exit 1
    else
      puts "✅ All assets verified"
    end
  end
end

# Run in CI pipeline before deployment
$ bin/rails assets:verify

# BAD: Multiple stylesheet_link_tag calls (unpredictable order)
<%= stylesheet_link_tag "application" %>
<%= stylesheet_link_tag "components" %>
<%= stylesheet_link_tag "utilities" %>

# GOOD: Single consolidated stylesheet or explicit ordering
# Option 1: Consolidate stylesheets
# app/assets/stylesheets/application.css
/* Load in specific order */
@import "normalize.css";
@import "variables.css";
@import "base.css";
@import "components.css";
@import "utilities.css";

# Option 2: Use data-turbo-track with explicit order
<%= stylesheet_link_tag "application", "data-turbo-track": "reload", media: "all" %>

# Use Dart Sass for preprocessing
# Gemfile
gem 'dartsass-rails'

# config/initializers/dartsass.rb
Rails.application.config.dartsass.builds = {
  "application.scss" => "application.css"
}

# app/assets/stylesheets/application.scss
// Explicit import order
@import "base/variables";
@import "base/mixins";
@import "base/reset";
@import "components/buttons";
@import "components/forms";
@import "layouts/header";
@import "layouts/footer";

Uncaught ReferenceError: $ is not defined
jQuery plugins not working
Bootstrap JavaScript not initializing

# config/importmap.rb

# Option 1: Pin from CDN (recommended for common libraries)
pin "jquery", to: "https://cdn.jsdelivr.net/npm/jquery@3.7.1/dist/jquery.min.js"
pin "bootstrap", to: "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"

# Option 2: Download to vendor/javascript and pin locally
$ bin/importmap pin jquery --download
$ bin/importmap pin bootstrap --download

# Option 3: For jQuery plugins requiring global $
# app/javascript/application.js
import $ from "jquery"
window.$ = window.jQuery = $  // Make jQuery global

import "jquery-ui"            // Now jQuery plugins work
import "select2"

# Pin Bootstrap JavaScript
# config/importmap.rb
pin "@popperjs/core", to: "https://cdn.jsdelivr.net/npm/@popperjs/core@2.11.6/dist/umd/popper.min.js"
pin "bootstrap", to: "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"

# app/javascript/application.js
import "@popperjs/core"
import "bootstrap"

// Initialize Bootstrap components
document.addEventListener("turbo:load", () => {
  const tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
  tooltipTriggerList.map(el => new bootstrap.Tooltip(el))
})

# Verify Propshaft is active
# config/application.rb
config.assets.pipeline = :propshaft

# Ensure image_tag uses asset pipeline
# app/views/layouts/application.html.erb
<%= image_tag "logo.png" %>
<!-- Should render: <img src="/assets/logo-abc123.png"> -->

# For images in CSS
/* app/assets/stylesheets/application.css */
.logo {
  background-image: url('/assets/logo.png');  /* ❌ Wrong */
  background-image: asset-url('logo.png');    /* ✅ Correct with sassc-rails */
}

# Or use inline styles with ERB
<div style="background-image: url(<%= asset_path('logo.png') %>)"></div>

# rails console
# Note: Propshaft doesn't expose load_path for scanning like Sprockets
# Use asset_path helpers to verify asset resolution instead

> helper.asset_path("logo.png")
# Should return digested path: "/assets/logo-abc123.png"

> helper.image_path("logo.png")
# Alternative helper for image assets

# Verify compiled assets exist in public/assets/
> Dir.glob(Rails.root.join("public/assets/logo-*.png"))
# Should return array of digested filenames

$ time RAILS_ENV=production bin/rails assets:precompile
real    2m14.382s  # Still slow!

# Identify bottlenecks
$ RAILS_ENV=production bin/rails assets:precompile --trace

# Look for slow tasks:
# ** Invoke dartsass:build (9.234s)
# ** Invoke javascript:build (18.542s)

# Optimize Dart Sass compilation
# package.json
{
  "scripts": {
    "build:css": "sass ./app/assets/stylesheets/application.scss:./app/assets/builds/application.css --style=compressed --no-source-map"
  }
}

# Parallel asset processing
# lib/tasks/assets.rake
namespace :assets do
  task precompile: :environment do
    # Run CSS and JS builds in parallel
    threads = []

    threads << Thread.new do
      system("npm run build:css")
    end

    threads << Thread.new do
      system("npm run build:js")
    end

    threads.each(&:join)

    # Then run Propshaft compilation (integrated with assets:precompile)
    Rake::Task["assets:precompile"].invoke
  end
end

# config/importmap.rb
# Cache remote imports locally for faster builds
$ bin/importmap pin jquery --download
$ bin/importmap pin bootstrap --download

# Now imports resolve locally instead of hitting CDN during build

# config/environments/development.rb
Rails.application.configure do
  # Enable asset debugging
  config.assets.debug = true

  # Serve assets through Rails
  config.public_file_server.enabled = true

  # Disable asset digesting in development
  config.assets.digest = false

  # Enable caching in development for faster reloads
  config.action_controller.perform_caching = true
  config.cache_store = :memory_store
end

# For CSS hot reload
# Gemfile
gem 'listen'  # File change detection

# config/environments/development.rb
config.file_watcher = ActiveSupport::EventedFileUpdateChecker

# app/views/layouts/application.html.erb
<!-- Disable preloading in development for faster reloads -->
<% if  Rails.env.development? %>
  <%= javascript_importmap_tags "application", async: false, defer: false %>
<% else  %>
  <%= javascript_importmap_tags %>
<% end  %>

# Gemfile
gem 'propshaft'

# config/application.rb
config.assets.pipeline = :propshaft

# Clean old Sprockets assets
$ bin/rails assets:clobber

# Compile new Propshaft assets
$ RAILS_ENV=production bin/rails assets:precompile

# Verify old assets are gone
$ ls public/assets/  # Should only show Propshaft digested files

# Gemfile
gem 'dartsass-rails'

# This compiles Sass before Propshaft processes assets
# app/assets/stylesheets/application.scss compiled to
# app/assets/builds/application.css (which Propshaft serves)

# Use esbuild for JavaScript bundling
# Gemfile
gem 'jsbundling-rails'

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

# Propshaft serves the bundled output from app/assets/builds/

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

# config/environments/production.rb
config.asset_host = 'https://cdn.example.com'

# Propshaft generates correct asset URLs automatically
# <img src="https://cdn.example.com/assets/logo-abc123.png">

# Keep Sprockets temporarily during migration
# Gemfile
gem 'propshaft'
gem 'sprockets-rails'  # Keep for rollback capability

# Switch back if needed
# config/application.rb
config.assets.pipeline = :sprockets  # Rollback

# Gemfile (after confirming migration success)
gem 'propshaft'
# gem 'sprockets-rails'  # Removed

# Gemfile
gem 'asset_sync'

# config/initializers/asset_sync.rb
AssetSync.configure do |config|
  config.fog_provider = 'AWS'
  config.aws_access_key_id = ENV['AWS_ACCESS_KEY_ID']
  config.aws_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
  config.fog_directory = ENV['FOG_DIRECTORY']
  config.fog_region = ENV['FOG_REGION']
end

# Automatically syncs compiled Propshaft assets to S3
$ RAILS_ENV=production bin/rails assets:precompile