Rails Propshaft Guide

With the first beta version of Rails 8, Propshaft has become the default asset pipeline for Rails.

Propshaft works quite differently to Sprockets. Mainly, all compilation, minification und concatenation tasks are outsourced to separate gems. The asset pipeline itself is only responsible for loading the assets and fingerprinting them, so they can be cached indefinitely.

This requires quite a different set up than before. This page tries to explain how Propshaft works, and how common use cases can be covered.

How Propshaft works

By default, Propshaft is configured to serve assets from app/assets, and vendor/assets. This allows developers to include them into their pages with the asset tag helpers like javascript_include_tag and stylesheet_link_tag. The assets are served directly in development mode, and copied to public/assets in production mode.

Placing the files in the correct folder and referencing them correctly can be difficult. The most common use cases are explained under the following links.

Dont't know yet what combination of options is the best?

JavaScript

• If you only write your own JS code and do not need any libraries, you need no additional gem. See Static JS.
• If you only rely on precompiled libraries (such as Lightbox2, Splide or similar) and some hand-written glue code, use Importmaps and Stimulus.
• If you need a bundler (such as Bun, esbuild or Webpack), use JS-Bundling.

CSS

• If you only write your own CSS code and don't need any libraries, you need no additional gem. See Static application CSS.
• If you additionally use some CSS libraries (such as Bootstrap Icons, or styles from Lightbox2), you need no additional gems either. See Static library CSS.
• If you want to write SASS code but otherwise don't need NodeJS, use the standalone SASS bundler.
• If you want to use Tailwind but otherwise don't need NodeJS, use the standalone Tailwind bundler.
• If you use NodeJS anyway, or need to use a CSS bundler (for libraries like Tailwind, Bootstrap or if you need Bulma or PostCSS), use CSS-Bundling.