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
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.cssoricons/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 |
Load paths |
|
|
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 | 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.
- Discovery. At boot, Propshaft assembles a load path. By default it includes the subdirectories of
app/assets,lib/assets, andvendor/assets, plus asset directories registered by gems and engines. You can add more throughconfig.assets.paths. - 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.svghas the logical pathicons/trash.svg. - 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.
- Precompilation. In production you run
assets:precompile. Propshaft copies every asset in the load path intopublic/assets, adds a digest to each filename, applies its small set of compilers, and writes a manifest file atpublic/assets/.manifest.json. - Helper resolution. When a view calls
image_tag "logo.svg"orstylesheet_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 fromconfig/application.rb. - Remove Sprockets-only settings such as
config.assets.compile,config.assets.js_compressor, andconfig.assets.css_compressorfrom your environment files. - If you are not using
require "rails/all", removerequire "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 |
|---|---|
| Directories searched for assets |
| Directories removed from the load path |
| A version string used to invalidate digests |
| URL prefix for assets (default |
| Where precompiled assets are written |
| Where the manifest file is written |
| Whether Propshaft serves assets itself (on by default in development and test) |
| Controls logging of asset requests |
| The list of compilers applied to files |
| Whether to check for changed files (on by default in development) |
| Prefix for apps served under a sub-URI |
| 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:
- Did
assets:precompilerun during the deploy? - Does
public/assets/.manifest.jsonexist in the deployed release? - Is the production server configured to serve files from
public, or is a web server or CDN set up to? - Is the asset in a directory that is actually in the load path in production?
- 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:
//= requireand//= linkdirectives in stylesheets and scripts.erb,.scss, or.sassfiles inapp/assets- Sprockets-specific helpers like
image-urlorasset-pathin 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
- Work on a branch and make sure the app is deployed with a reliable test suite or manual check list.
- Swap the gem:
- gem "sprockets-rails"
+ gem "propshaft"
- Remove the Sprockets configuration listed earlier.
- Replace directive-based bundling: either split files into separate tags, adopt importmap-rails, or introduce jsbundling-rails or cssbundling-rails.
- Replace Sass or ERB assets by switching to plain CSS or a processing tool, then use
excluded_pathsfor any source directories. - Update CSS references to use
url()with logical paths. - Run
assets:precompilelocally in production mode and open the app, checking the browser’s network tab for 404s. - 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 invendor/assets, and use subdirectories to group related files, such asicons/orfonts/. - 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:precompilein a production-like environment before releasing, rather than trusting development behavior. - Debug with the load path. When an asset is missing, inspect
config.assets.pathsand 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.