Core Concepts

Propshaft is built on a few simple but powerful concepts. Understanding them will help you use the library effectively.

Load Path

The load path is the set of directories where Propshaft looks for asset source files. By default, it includes app/assets, lib/assets, and vendor/assets from your application and any included Rails engines or gems.

You can customize the load path in your application's configuration. See the Configuration guide for more details on config.assets.paths.

Propshaft treats all directories in the load path as a single, virtual filesystem. If two assets have the same path (e.g., application.js) in different load path directories, the one from the directory that appears first in the config.assets.paths array takes precedence. Application paths (app/assets) are typically prioritized over paths from gems.

Digest Stamping

To allow for aggressive browser and CDN caching, Propshaft stamps each asset filename with a digest (a hash of its content).

For example, application.css might become application-a1b2c3d4e5f6a7b8.css.

This process happens during the assets:precompile Rake task, which is typically run during deployment. Because the filename changes whenever the content changes, you can safely configure servers to cache these assets indefinitely (public, max-age=31536000, immutable).

In development, digests are still used in asset URLs but are calculated on-the-fly. This ensures that asset paths remain consistent between development and production.

Manifest File

After running assets:precompile, Propshaft generates a manifest file, typically located at public/assets/.manifest.json. This JSON file contains a mapping of logical asset paths to their corresponding digested paths.

A sample entry might look like this:

{
  "application.js": {
    "digested_path": "application-888761f8.js",
    "integrity": "sha384-BIr0kyMRq2sfytK/T0XlGjfav9ZZrWkSBC2yHVunCchnkpP83H28/UtHw+m9iNHO"
  }
}

In production, Rails view helpers use this manifest to look up the correct digested path for a given logical path, ensuring your views always reference the correct version of an asset.

Resolvers

Propshaft uses two different strategies, or "resolvers," for finding and serving assets, depending on the environment.

Dynamic Resolver

In the development environment, Propshaft uses a dynamic resolver. When a request for an asset arrives, the dynamic resolver searches the load path for the source file, compiles it if necessary, calculates its digest, and serves the content. This happens on-demand for each request, ensuring that any changes you make to asset files are reflected immediately without a server restart.

Static Resolver

In the production environment, Propshaft switches to a static resolver. This resolver relies entirely on the pre-generated .manifest.json file. It looks up the logical path in the manifest to find the digested path and assumes the corresponding file exists on disk in the public/assets directory.

The presence of the manifest file is what triggers the switch to the static resolver. This approach is much faster and more efficient for production as it involves a simple hash lookup and serving a static file, with no on-the-fly compilation or file system searches.