DOCSEARCHbyAlgolia
Submit Docs

Propshaft Documentation

repository·main·Indexed 21 days ago

https://github.com/rails/propshaft

A modern, lightweight asset pipeline for Rails designed for Node-based bundling and high-bandwidth connections. Propshaft provides a configurable load path, digest stamping for caching, and efficient asset serving without full transpilation. It is the default asset pipeline for Rails 8 and supports Subresource Integrity (SRI) using SHA-2 family algorithms, custom asset compilers, and integration with standard Rails asset helpers.

Tokens
6.6K
Snippets
31
Records
37
Agent score
77%

What's inside Propshaft

  1. Bypass the digest step for pre-digested files

    main

    If you need to provide files that refer to each other through Propshaft (for example, a JavaScript file and its corresponding source map) while maintaining stable filenames, you can bypass the digest step.

    Propshaft recognizes files that have already been digested if they follow the pattern -[digest].digested.[extension] (e.g., myfile-abc123def.digested.js).

  2. Install Propshaft

    main

    Propshaft is the default asset pipeline for Rails 8 applications. For Rails 7 applications, you can start a new application with Propshaft by using the -a propshaft flag.

    For existing applications, refer to the official upgrade guide for step-by-step instructions.

    rails new myapp -a propshaft

  3. Improve development performance with EventedFileUpdateChecker

    main

    By default, Propshaft uses ActiveSupport::FileUpdateChecker to check for asset updates. For projects with a large number of assets, you can improve performance by using the listen gem and switching to the evented checker.

    1. Add gem 'listen' to your development group in the Gemfile.
    2. Set the following in config/environments/development.rb:
    config.file_watcher = ActiveSupport::EventedFileUpdateChecker

  4. Migrating from Sprockets

    main

    Migrating from Sprockets to Propshaft requires architectural changes because Propshaft does not provide transpilation (like CoffeeScript or Sass) by design.

    • If you rely on Sprockets for transpiling: You must either stop transpiling or switch to a Node-based transpiler using gems like jsbundling-rails or cssbundling-rails.
    • If you already use Node-based bundling: Propshaft integrates easily as it only handles digesting and serving the final assets.
    • For greenfield apps: If using the default import-map approach, Propshaft works well with vanilla CSS.

  5. Migrate from Sprockets to Propshaft

    main

    Migrating from Sprockets to Propshaft requires several steps to adjust how assets are handled and referenced.

    Migration Steps

    1. Remove sprockets, sprockets-rails, and sass-rails from your Gemfile and add propshaft.
    2. Run ./bin/bundle install.
    3. Check Gemfile.lock for any gems that depend on sprockets or sprockets-rails and update them if necessary.
    4. In config/application.rb, remove config.assets.paths << Rails.root.join('app','assets').
    5. Remove app/assets/config/manifest.js.
    6. If you are not using require "rails/all", remove require "sprockets/railtie" from your application configuration.

    Asset Paths and Discovery

    Propshaft automatically includes vendor/assets, lib/assets, and app/assets (and those from gems) in its search paths. To see all included files, run:

    rake assets:reveal

    Updating CSS Asset References

    Propshaft does not use Sprockets-style asset helpers like image_url. Instead, it uses standard CSS url() functions. You must update your CSS files to use relative or absolute paths starting with /.

    Important: Path Behavior Change

    • Sprockets used absolute paths (e.g., image_url('hero.jpg')).
    • Propshaft uses relative paths by default. If a CSS file is in assets/stylesheets/theme/main.scss, a reference to url('hero.jpg') will look in assets/stylesheets/theme/hero.jpg.
    • To reference an asset from the root of your asset paths, use a leading slash: url('/hero.jpg').

    Example Transformation:

    - background: image_url('hero.jpg');
+ background: url('/hero.jpg');

  6. Reference assets in views

    main

    Assets can be referenced using their logical paths via standard Rails asset helpers. In production, these logical references are automatically converted into digest-aware paths using the manifest file located at public/assets/.manifest.json.

    Supported helpers include:

    • asset_path
    • image_tag
    • javascript_include_tag
    • and other standard asset helper tags.

  7. Migrate from sass-rails to cssbundling-rails

    main

    If your application uses sass-rails for CSS bundling, migrate to cssbundling-rails:

    1. Add cssbundling-rails to your Gemfile.
    2. Run ./bin/bundle install.
    3. Run ./bin/rails css:install:sass.

    Managing Multiple Entrypoints

    To avoid compilation errors with @import and variables when using multiple entrypoints, separate your entrypoints from your source files.

    Recommended Structure:

    • app/assets/stylesheets/entrypoints/admin.scss
    • app/assets/stylesheets/entrypoints/application.scss
    • app/assets/stylesheets/sources/admin/source_1.scss
    • app/assets/stylesheets/sources/application/source_1.scss

    Then, update the build:css attribute in package.json to point to the entrypoints directory:

    "build:css": "sass ./app/assets/stylesheets/entrypoints:./app/assets/builds --no-source-map --load-path=node_modules"
    ./bin/rails css:install:sass

  8. Extract Sass/SCSS from JavaScript in jsbundling-rails

    main

    If you previously used Webpacker's extract_css to include Sass/SCSS files within JavaScript (e.g., import '../scss/application.scss'), you must manually configure mini-css-extract-plugin in your webpack.config.js after migrating to jsbundling-rails.

    1. Install dependencies: yarn add mini-css-extract-plugin sass sass-loader css-loader
    2. Configure webpack.config.js with the plugin and loaders.
    const path    = require("path")
const webpack = require("webpack")
const MiniCssExtractPlugin = require("mini-css-extract-plugin")

module.exports = {
  mode: "production",
  devtool: "source-map",
  entry: {
    application: "./app/javascript/application.js"
  },
  resolve: {
    modules: ["app/javascript", "node_modules"],
  },
  output: {
    filename: "[name].js",
    sourceMapFilename: "[file].map",
    path: path.resolve(__dirname, "app/assets/builds"),
  },
  plugins: [
    new MiniCssExtractPlugin(),
    new webpack.optimize.LimitChunkCountPlugin({
      maxChunks: 1
    })
  ],
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader", "sass-loader"],
      },
    ],
  },
}

  9. Migrate from Webpacker to jsbundling-rails

    main

    Because Propshaft has a smaller scope than Sprockets, you must migrate your JavaScript bundling from Webpacker to jsbundling-rails.

    Migration Steps

    1. Replace webpacker with jsbundling-rails in your Gemfile.
    2. Run ./bin/bundle install.
    3. Run ./bin/rails javascript:install:webpack.
    4. Remove the following files/folders:
      • config/initializers/assets.rb
      • bin/webpack
      • bin/webpack-dev-server
      • config/webpack (migrate custom config to webpack.config.js)
      • config/webpacker.yml
    5. Replace all instances of javascript_pack_tag with javascript_include_tag and add defer: true to them.

    Key Changes

    • ./bin/dev and Procfile.dev: Use ./bin/dev to start both rails s and yarn build (which replaces webpack-dev-server) simultaneously.
    • webpack.config.js: This is now a top-level file you can edit directly. If you have multiple entrypoints, update the entry attribute:
    module.exports = {
  entry: {
    application: "./app/javascript/application.js",
    admin: "./app/javascript/admin.js"
  }
}
    • Module Resolution: Webpacker automatically included app/javascript/ in resolution. To maintain this behavior in jsbundling-rails, add the following to webpack.config.js:
    module.exports = {
  // ...
  resolve: {
    modules: ["app/javascript", "node_modules"],
  },
  // ...
}

    Alternatively, use relative imports (e.g., import './channels').

    ./bin/rails javascript:install:webpack

  10. Use SRI in your views

    main

    Once config.assets.integrity_hash_algorithm is configured, pass integrity: true to asset helpers to generate HTML with integrity hashes.

    Important: SRI only works in secure contexts (HTTPS) or during local development. Integrity hashes are automatically omitted when serving over HTTP in production.

    <%= stylesheet_link_tag "application", integrity: true %>
<%= javascript_include_tag "application", integrity: true %>

  11. Reference digested assets in CSS and JavaScript

    main

    CSS

    Propshaft automatically converts asset references within CSS files to use digested filenames. For example, background: url("/bg/pattern.svg") will be transformed to background: url("/assets/bg/pattern-2169cbef.svg") before serving.

    JavaScript

    To reference digested assets in JavaScript, you must manually use the RAILS_ASSET_URL pseudo-method. This ensures the logical path is transformed into the correct digest-aware path at runtime.

    export default class extends Controller {
  init() {
    // This will be transformed into a path like "/assets/icons/trash-54g9cbef.svg"
    this.img = RAILS_ASSET_URL("/icons/trash.svg")
  }
}

  12. Configure asset load and excluded paths

    main

    Propshaft makes all assets from directories configured in config.assets.paths available for serving. During precompilation, all these assets are copied into public/assets.

    You can use config.assets.excluded_paths to prevent specific directories from being part of the load path. This is useful if a directory contains source files (like app/assets/stylesheets) intended only as inputs for an external compiler (e.g., Dart Sass) and should not be served directly.

    Note: You must provide full paths when using excluded paths, such as Rails.root.join("app/assets/stylesheets").