Rails Asset Pipeline: Propshaft Explained

Learn how Propshaft serves, fingerprints, and delivers Rails assets, how it differs from Sprockets, and how to deploy it safely.


By Jean Emmanuel Cadet • 21 min read

Rails Asset Pipeline: Propshaft Explained
Share with friends

Every Rails application ships more than Ruby code. Behind each page sit stylesheets, JavaScript files, images, fonts, and icons, and the browser has to find all of them, download them, and cache them sensibly. If that process is sloppy, you get broken images after a deploy, users stuck on an old stylesheet, or a layout that looks fine on your laptop and wrong in production.

Rails solves this with an asset pipeline: a set of conventions and tools that decide where static files live, how they are named when served, and how your views refer to them. For most of Rails’ history that job belonged to Sprockets. Since Rails 8, new applications use Propshaft by default, a smaller library built around a narrower idea of what an asset pipeline should do.

This article explains Propshaft from the ground up. You will learn what it does and what it deliberately does not do, how fingerprinting works, how to install and configure it, how to deploy with it, and how to debug the problems that show up most often. It is written to work as a reference you can come back to.


What Is the Rails Asset Pipeline?

Before looking at Propshaft, it helps to define a few terms.

  • Static asset: a file the browser downloads as-is, such as a CSS file, a JavaScript file, an image, or a font.
  • Logical path: the name you use in your code to refer to an asset, for example application.css or icons/trash.svg.
  • Load path: the list of directories Rails searches when it needs to turn a logical path into a real file.
  • Digest (or fingerprint): a short hash of a file’s contents, added to the filename so the name changes whenever the content changes.

The asset pipeline connects these ideas. It lets you keep files organized in directories like app/assets/stylesheets, refer to them with simple helpers like stylesheet_link_tag "application", and have Rails produce the correct public URL, including the digest, in the final HTML.

Without a pipeline, you would hard-code URLs such as /css/site.css in your layouts. That works until you want long-lived browser caching, because a cached file with an unchanged name never gets refreshed when you edit it. The pipeline solves this by generating unique filenames per version of a file and letting your views refer to the stable logical name.

In short, the asset pipeline organizes your static files, resolves logical names to real files, fingerprints them for caching, and gets them ready to serve in production.


What Is Propshaft?

Propshaft is an asset pipeline library for Rails. It handles the delivery side of the problem: finding files in your load path, serving them in development, copying them with digested filenames during precompilation, and writing a manifest that maps logical paths to digested ones.

It was introduced as a simpler alternative to Sprockets, and it became the default for new applications in Rails 8. On Rails 7, you can opt in when generating an app:

rails new myapp --asset-pipeline=propshaft

The key to understanding Propshaft is its scope. It does not concatenate your files, minify them, transpile modern JavaScript, or compile Sass. Its documentation is explicit that it was not designed to provide full transpiler capabilities. Those jobs now belong to other tools: native browser features such as ES modules through import maps, or dedicated bundlers like esbuild and processors like Tailwind or Dart Sass, wired in through gems such as jsbundling-rails and cssbundling-rails.

That narrow scope is a design choice. Propshaft aims to be small and predictable, and it leaves compilation to tools that specialize in it.


A Brief History of Rails Asset Management

Sprockets arrived with Rails 3.1 and gave Rails a complete asset toolchain. At the time, browsers had no native module system, JavaScript tooling lived mostly outside the Ruby world, and compiling CoffeeScript or Sass inside Rails was a real convenience. Sprockets provided directives such as //= require, concatenation of many files into one, preprocessors for languages like Sass and ERB, and compression.

Over the following years the surrounding ecosystem changed. Browsers gained native ES module support. HTTP/2 made serving several small files less costly than it once was in many setups. Node-based tools such as esbuild and webpack became mature, and CSS gained features such as custom properties and nesting. Rails 7 responded by offering new options: importmap-rails for buildless JavaScript, and jsbundling-rails and cssbundling-rails for apps that need a bundler.

Once those options existed, the all-in-one pipeline overlapped with tools developers were already choosing. Propshaft takes a different philosophy: do fingerprinting and delivery well, and let other tools handle transformation. Rails 8 made it the default for new applications.

This is a difference in design philosophy, not a verdict on Sprockets. Sprockets remains a capable, widely used library, and many production applications depend on its features. A new project can opt into it, and an existing project has no obligation to move. The right choice depends on what your application needs.


Propshaft vs. Sprockets

Here is how the two compare across the areas that matter in practice.

Area

Propshaft

Sprockets

Asset discovery

Everything in the configured load path is available

Files must be declared for precompilation (for example in manifest.js)

Load paths

config.assets.paths, with config.assets.excluded_paths to exclude directories

config.assets.paths plus a precompile list

Serving

Development server, no precompile needed

Development server with on-demand compilation

Fingerprinting

Digests added during precompilation, resolved through a manifest

Digests added during precompilation, resolved through a manifest

CSS and JS processing

Minimal: rewrites url() references in CSS and source map comments

Directives, concatenation, preprocessors, compressors

Legacy compatibility

Does not support Sprockets directives or helpers

Supports a long-standing set of conventions and gems

Extensibility

Small set of options and a compiler list

Rich plugin ecosystem of processors and transformers

Asset discovery and load paths

Propshaft makes every file in every configured load path available, and it copies all of them into public/assets when you precompile. Sprockets works differently: it only copied files that were explicitly included in a bundle or listed for precompilation. With Propshaft, you can exempt directories through config.assets.excluded_paths.

Serving and fingerprinting

Both libraries fingerprint filenames during precompilation and use a manifest to translate logical names into digested ones. The practical difference is how much happens around that step.

Processing and compilation

Sprockets can concatenate, compile, and compress. Propshaft rewrites asset references inside CSS and source map comments, and that is essentially all. If you need Sass, PostCSS, TypeScript, or JSX, you add a separate tool.

Legacy compatibility and extensibility

Propshaft does not understand Sprockets directives like //= require or //= link, and it does not provide Sprockets-style helpers such as image_url inside CSS. Applications that lean heavily on those features, or on gems that register Sprockets processors, will need work before they can switch, or may be better off staying put.

Propshaft is intentionally simpler and does not try to replace every feature Sprockets provides. Whether that is an advantage depends entirely on your application.


How Propshaft Works

Propshaft’s workflow can be followed in five steps.

  1. Discovery. At boot, Propshaft assembles a load path. By default it includes the subdirectories of app/assets, lib/assets, and vendor/assets, plus asset directories registered by gems and engines. You can add more through config.assets.paths.
  2. Logical paths. Each file gets a logical path relative to the root of the load path directory it lives in. A file at app/assets/images/icons/trash.svg has the logical path icons/trash.svg.
  3. Development serving. In development (and test), Propshaft serves assets on demand. There is no precompile step. It watches for file changes so edits show up on reload.
  4. Precompilation. In production you run assets:precompile. Propshaft copies every asset in the load path into public/assets, adds a digest to each filename, applies its small set of compilers, and writes a manifest file at public/assets/.manifest.json.
  5. Helper resolution. When a view calls image_tag "logo.svg" or stylesheet_link_tag "application", the helper asks Propshaft to resolve the logical path. If a precompiled manifest exists, the digested URL from the manifest is used. Otherwise Propshaft resolves it dynamically from the load path.

The two compilers Propshaft ships with are worth naming, because they are the only transformations it performs on file contents. One rewrites url() references in CSS so they point to digested filenames. The other rewrites source mapping comments in CSS and JavaScript the same way. Everything else is copied byte for byte.


Understanding Asset Fingerprinting

Fingerprinting means adding a hash of the file’s contents to its filename. Instead of application.css, the browser requests something like application-2169cbef.css.

Why it matters for caching

Browsers can cache a file for a very long time if they are sure it will not change. A fingerprinted filename gives them that guarantee: if the content changes, the filename changes, so the browser treats it as a brand new resource. You can tell browsers to cache fingerprinted files for a year, and still ship an updated stylesheet that users receive immediately, because your HTML now points to a new URL.

What fingerprinting is not

Fingerprinting is often confused with two other things:

  • It is not compression. The file is not made smaller. Compression (gzip or Brotli) is typically handled by your web server or CDN.
  • It is not minification. Propshaft does not remove whitespace or rename variables in your code.

Fingerprinting only changes the name.

How Rails resolves references

You always write the logical name in your code:

<%= stylesheet_link_tag "application" %>

In production, Propshaft looks up application.css in the manifest and outputs the digested URL. In CSS, a reference like url("/bg/pattern.svg") is rewritten to include the digest of that file before the stylesheet is served.

Pre-digested files

If two files refer to each other by name, for example a JavaScript file and its source map, you cannot let Propshaft digest them independently, because neither can know the other’s final name. In that case, digest them in advance. Propshaft recognizes files that already follow the pattern name-[digest].digested.js as already digested and leaves their names alone.

Cache busting for everything at once

If you ever need to invalidate all digests, config.assets.version is a setting you can change. It is covered in the configuration section.


Installing and Configuring Propshaft

New Rails applications

On Rails 8 and later, there is nothing to install. rails new generates an application with Propshaft already in the Gemfile and a layout that uses it. If you prefer Sprockets for a new app, you can ask for it explicitly:

rails new myapp --asset-pipeline=sprockets

On Rails 7, pass --asset-pipeline=propshaft (or -a propshaft) as shown earlier.

Existing applications

For an app that currently uses Sprockets, start with the Gemfile:

# Gemfile
gem "propshaft"

Then remove sprockets-rails and any Sprockets-specific gems you were using, and run:

bundle install

After that, clean up the Sprockets configuration:

  • Delete app/assets/config/manifest.js.
  • Remove config.assets.paths << Rails.root.join("app", "assets") and similar lines from config/application.rb.
  • Remove Sprockets-only settings such as config.assets.compile, config.assets.js_compressor, and config.assets.css_compressor from your environment files.
  • If you are not using require "rails/all", remove require "sprockets/railtie".

Then check your stylesheets and scripts for Sprockets features. The migration section below covers that in detail.

The layout in a default Rails 8 app

A generated layout looks like this:

<%= stylesheet_link_tag :app, "data-turbo-track": "reload" %>
<%= javascript_importmap_tags %>

stylesheet_link_tag :app is a Propshaft extension. It includes all stylesheets from your application’s own app/assets directories. There is also :all, which includes stylesheets from every path in the load path, including gems and engines.


Understanding the Asset Directory

Rails apps traditionally have three asset locations:

  • app/assets: assets that belong to your application: your stylesheets, images, and fonts.
  • lib/assets: assets for code that is shared across applications but is not a gem.
  • vendor/assets: third-party assets you copy into the project, such as a vendored icon font.

Each of these has subdirectories, commonly images, stylesheets, and javascript. Each existing subdirectory becomes its own root in the load path. That is why app/assets/stylesheets/application.css is referenced as application.css, not stylesheets/application.css.

How load paths affect discovery

Logical paths are relative to their load path root, so the directory structure inside that root becomes part of the name:

app/assets/images/logo.svg            -> logo.svg
app/assets/images/icons/trash.svg -> icons/trash.svg
app/assets/stylesheets/admin.css -> admin.css
vendor/assets/fonts/inter.woff2 -> inter.woff2

Two consequences follow. First, if two directories contain files with the same logical path, one will shadow the other, with earlier entries in the load path taking precedence. Second, the folder name images or stylesheets does not appear in the URL, so you do not write it in your helpers.

Gems and engines can also contribute directories. If you use importmap-rails, it adds app/javascript to the load path so your modules can be served. When something unexpected appears (or fails to appear), inspect the load path instead of guessing:

# In a Rails console
Rails.application.config.assets.paths

Working with CSS, JavaScript, and Images

Adding a new stylesheet

Create app/assets/stylesheets/admin.css:

.admin-banner {
background-color: #0b1b3a;
color: #ffffff;
padding: 0.75rem 1rem;
}

Then include it in a layout or view:

<%= stylesheet_link_tag "admin" %>

If your main layout uses stylesheet_link_tag :app, admin.css is already included on every page, because :app includes all stylesheets in your app’s asset directories. If you want it only on admin pages, use a dedicated layout and reference stylesheets by name there, or organize things so that only the intended files live in the directories :app covers.

Referencing images from views

Place app/assets/images/logo.svg and use the usual helpers:

<%= image_tag "logo.svg", alt: "CodeCurious logo", class: "site-logo" %>
<%= image_tag "icons/trash.svg", alt: "Delete" %>

image_tag resolves the logical path, adds the digest in production, and renders an <img> tag. If you only need the URL, use asset_path:

<link rel="preload" href="<%= asset_path("inter.woff2") %>" as="font" type="font/woff2" crossorigin>

Use asset_path anywhere you need a URL string rather than a tag, such as in a preload hint or a data attribute.

Referencing assets from CSS

Inside a stylesheet, use a normal url() with a path that starts with /, based on the asset’s logical path:

.hero {
background-image: url("/backgrounds/hero.jpg");
}

If the file is app/assets/images/backgrounds/hero.jpg, Propshaft rewrites this to the digested URL before serving the stylesheet. Sprockets-style helpers such as image-url() or ERB inside CSS are not available.

Referencing assets from JavaScript

JavaScript references are not rewritten automatically. When a script needs the digested URL of an asset, Propshaft provides the RAILS_ASSET_URL pseudo-function:

javascript

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
connect() {
this.iconUrl = RAILS_ASSET_URL("/icons/trash.svg")
}
}

This is a marker that Propshaft’s compiler replaces with the digest-aware path when the file is served or precompiled. It is not an actual runtime function.

Assets that are not part of the pipeline

User uploads, such as profile photos and documents, do not belong in the asset pipeline. They are created at runtime, so they cannot be fingerprinted at deploy time. Rails handles them with a separate system. If you are working with uploaded files, see this practical guide to Rails Active Storage.


CSS and JavaScript Processing

This is where most confusion about Propshaft comes from, so it is worth being direct.

Propshaft is not:

  • a JavaScript bundler,
  • a JavaScript transpiler (it will not compile JSX, TypeScript, or modern syntax down for older browsers),
  • a CSS preprocessor (it will not compile Sass or Less),
  • a minifier or concatenator.

It copies your files, fingerprints them, and rewrites a few references. If a file needs to be transformed first, a different tool must do it.

Working with importmap-rails

For many applications, no processing is needed. importmap-rails lets the browser load ES modules directly, and Propshaft serves and fingerprints them. Your config/importmap.rb maps module names to files:

# config/importmap.rb
pin "application"
pin_all_from "app/javascript/controllers", under: "controllers"

Propshaft’s role here is to serve and digest the files that the import map points to. The browser does the module loading. This combination fits well with plain CSS, which now supports variables, nesting, and many features that once required Sass.

Working with jsbundling-rails

If you need a bundler, for example because you use npm packages, JSX, or TypeScript, jsbundling-rails runs a tool like esbuild and writes the output into app/assets/builds. Propshaft then serves and fingerprints the built file like any other asset:

bundle add jsbundling-rails
bin/rails javascript:install:esbuild
<%= javascript_include_tag "application", "data-turbo-track": "reload", defer: true %>

Working with cssbundling-rails

For Sass, PostCSS, Tailwind, or Bootstrap, cssbundling-rails does the same for CSS:

bundle add cssbundling-rails
bin/rails css:install:sass

The source files remain in app/assets/stylesheets, and the compiled output lands in app/assets/builds. In this setup, you usually do not want Propshaft to copy the raw source files into public/assets, which is exactly what excluded_paths is for (see the next section).

The pattern is consistent: another tool produces the final files, and Propshaft handles delivery. You are not asking Propshaft to do work it was not designed for.


Configuration and Customization

Propshaft reads its settings from config.assets. The following options exist in the library:

Option

Purpose

config.assets.paths

Directories searched for assets

config.assets.excluded_paths

Directories removed from the load path

config.assets.version

A version string used to invalidate digests

config.assets.prefix

URL prefix for assets (default /assets)

config.assets.output_path

Where precompiled assets are written

config.assets.manifest_path

Where the manifest file is written

config.assets.server

Whether Propshaft serves assets itself (on by default in development and test)

config.assets.quiet

Controls logging of asset requests

config.assets.compilers

The list of compilers applied to files

config.assets.sweep_cache

Whether to check for changed files (on by default in development)

config.assets.relative_url_root

Prefix for apps served under a sub-URI

config.assets.integrity_hash_algorithm

Hash algorithm for Subresource Integrity (available in recent Propshaft versions)

Most applications never touch these. Here are the ones you are most likely to need.

Adding a custom asset path

Register extra directories in config/initializers/assets.rb, using full paths:

# config/initializers/assets.rb
Rails.application.config.assets.paths << Rails.root.join("vendor/fonts")

Files in vendor/fonts can now be referenced by their logical paths. Use this for directories that do not follow the standard layout, such as a folder of fonts you maintain yourself.

Excluding source directories

When a compiler produces the files you actually serve, exclude the inputs:

# config/application.rb
module MyApp
class Application < Rails::Application
config.load_defaults 8.1

config.assets.excluded_paths = [Rails.root.join("app/assets/stylesheets")]
end
end

Use full paths, not relative strings. Without this, the raw Sass or source files would be copied into public/assets alongside the compiled output.

Changing the asset version

# config/initializers/assets.rb
Rails.application.config.assets.version = "2"

Changing this value changes the digests, which forces browsers to fetch fresh copies of everything. It is a blunt tool, useful when you need to bust caches globally.

Subresource Integrity

Recent Propshaft versions support Subresource Integrity (SRI), which lets browsers verify that a file has not been altered:

# config/initializers/assets.rb
Rails.application.config.assets.integrity_hash_algorithm = "sha384"
<%= stylesheet_link_tag :app, integrity: true %>

Check your installed version’s documentation before relying on this, since it is a newer addition.


Deploying Rails Applications with Propshaft

In development, Propshaft serves assets on demand. Production works differently, and most “works on my machine” asset bugs come from that gap.

Precompiling

Before the app serves traffic, run:

RAILS_ENV=production SECRET_KEY_BASE_DUMMY=1 bin/rails assets:precompile

This copies all assets into public/assets with digested names and writes .manifest.json. SECRET_KEY_BASE_DUMMY=1 lets the task run at build time without real secrets. Rails’ default Dockerfile uses the same approach.

Serving fingerprinted files

Once public/assets exists, something has to serve it. That is usually the Rails static file server, or a web server or CDN in front of it. In recent Rails versions, the generated config/environments/production.rb includes a long-lived cache header for digested files:

# config/environments/production.rb
config.public_file_server.headers = { "cache-control" => "public, max-age=#{1.year.to_i}" }

A one-year cache is safe here only because filenames are fingerprinted. Do not apply the same header to non-fingerprinted files. If your Rails version’s generated config gates static file serving behind an environment variable such as RAILS_SERVE_STATIC_FILES, check that it is set in your deployment.

If you use a CDN, config.asset_host points asset URLs at it:

config.asset_host = "https://cdn.example.com"

Cleaning up

Two Rake tasks help manage the output directory: assets:clean removes old digested versions while keeping recent ones, and assets:clobber removes the precompiled assets entirely.

Why correct deployment matters

During a rolling deploy, some users may have HTML from the old release that references old digests. If you delete old digested files immediately, those pages break. Keeping recent versions around, which assets:clean is designed for, avoids that.


Common Problems and Troubleshooting

Missing assets

An error like Propshaft::MissingAssetError means a logical path could not be found in the load path. Check the spelling, then check the directory the file lives in, and confirm it is actually in the load path:

Rails.application.assets.load_path.find("logo.svg")

If this returns nil, Propshaft cannot see the file. Look for a typo, a file outside the standard directories, or an excluded_paths entry that is hiding it.

Incorrect asset paths

Do not include images/ or stylesheets/ in helper arguments. Use image_tag "logo.svg", not image_tag "images/logo.svg". In CSS, start paths with / and use the logical path.

Works in development, fails in production

Walk through this checklist:

  1. Did assets:precompile run during the deploy?
  2. Does public/assets/.manifest.json exist in the deployed release?
  3. Is the production server configured to serve files from public, or is a web server or CDN set up to?
  4. Is the asset in a directory that is actually in the load path in production?
  5. Did you reference the asset with a logical path rather than a hard-coded /assets/... URL?

Remember that config.assets.server is on by default only in development and test. In production, Propshaft is not serving anything on demand.

Stale references and stale files in development

If a precompiled public/assets directory is left over in your development environment, Propshaft may resolve assets from the manifest instead of the live files, so your edits seem to do nothing. Remove it:

bin/rails assets:clobber

In production, stale pages that reference deleted digests usually mean old assets were removed too early during a deploy.

Missing fingerprinted files

If the HTML references application-abc123.css but the file returns a 404, the HTML and the public/assets directory came from different builds. This often happens with multiple servers where only some received the new assets, or when the precompile step ran in a different build stage from the one that was deployed.

Sprockets features that no longer work

Symptoms include //= require lines appearing as plain comments, Sass syntax failing in .css files, or .erb assets not being processed. These are not bugs. Propshaft does not provide those features, so replace them with plain CSS, a bundler, or a processing gem as appropriate.


Migration from Sprockets to Propshaft

Migration is optional. If your application works well with Sprockets, there is no requirement to change.

When migration makes sense

It is worth considering if you already use importmap-rails or a JavaScript or CSS bundler for most of your processing, if you want a smaller and more predictable pipeline, or if your Sprockets usage is mostly serving static files.

What to inspect first

Audit your application for:

  • //= require and //= link directives in stylesheets and scripts
  • .erb, .scss, or .sass files in app/assets
  • Sprockets-specific helpers like image-url or asset-path in stylesheets
  • gems that register Sprockets processors or depend on Sprockets
  • custom precompile lists in config.assets.precompile
  • JavaScript or CSS compression settings in environment files

The more of these you rely on, the more work the migration involves.

A practical approach

  1. Work on a branch and make sure the app is deployed with a reliable test suite or manual check list.
  2. Swap the gem:
- gem "sprockets-rails"
+ gem "propshaft"
  1. Remove the Sprockets configuration listed earlier.
  2. Replace directive-based bundling: either split files into separate tags, adopt importmap-rails, or introduce jsbundling-rails or cssbundling-rails.
  3. Replace Sass or ERB assets by switching to plain CSS or a processing tool, then use excluded_paths for any source directories.
  4. Update CSS references to use url() with logical paths.
  5. Run assets:precompile locally in production mode and open the app, checking the browser’s network tab for 404s.
  6. Deploy to a staging environment before production.

If the audit reveals a large amount of Sprockets-specific code, staying on Sprockets is a perfectly reasonable decision.


Best Practices

  • Keep the pipeline simple. Use the fewest tools your app needs. Plain CSS and import maps cover more cases than they once did.
  • Use logical paths everywhere. Never hard-code /assets/... URLs or digests in views or CSS.
  • Organize by purpose. Keep your own files in app/assets, third-party files in vendor/assets, and use subdirectories to group related files, such as icons/ or fonts/.
  • Exclude compiler inputs. If a tool compiles files into app/assets/builds, exclude the source directory so raw sources are not published.
  • Avoid unnecessary processing. Add a bundler only when you have a concrete need for one.
  • Test the production path. Run assets:precompile in a production-like environment before releasing, rather than trusting development behavior.
  • Debug with the load path. When an asset is missing, inspect config.assets.paths and the manifest before changing anything.
  • Keep perspective on page speed. Asset delivery is one piece of the picture. Slow pages are often caused by server-side work, so it is worth reviewing database access as well, for example with these tips on optimizing Active Record queries in Rails.

Conclusion

Propshaft is a focused asset pipeline: it finds files in your load path, serves them in development, copies and fingerprints them for production, and rewrites a small number of references so everything keeps working. It does not bundle, transpile, minify, or compile, and that is by design. When your app needs those things, tools like importmap-rails, jsbundling-rails, and cssbundling-rails handle them, and Propshaft delivers the result.

Compared with Sprockets, Propshaft trades breadth for simplicity. That trade suits new Rails 8 applications, apps that rely on import maps or external bundlers, and teams that want fewer moving parts. Sprockets remains a good fit for applications that depend on directives, preprocessors, or Sprockets-specific gems, and nothing forces a move.

Whichever you choose, the same fundamentals apply: understand your load path, use logical paths, test the production build, and keep each tool responsible for one job.

Jean Emmanuel Cadet
Written by Jean Emmanuel Cadet
Jean Emmanuel is a Full-Stack Software Engineer specializing in Ruby on Rails and the modern Rails ecosystem. He builds scalable, maintainable web applications using Rails, Hotwire (Turbo & Stimulus), PostgreSQL, and SQLite, with a focus on fast, dynamic user experiences. Through CodeCurious, he shares practical lessons, development insights, and real-world solutions for modern developers.

Code. Learn. Grow.

A friendly newsletter sharing dev tips, lessons, and wins from my journey.