Master the Rails Asset Pipeline: Best Practices for Apps & Gems

Overview

This talk, delivered by Adrian Marin at RailsConf 2025, dives deeply into understanding and mastering the Rails asset pipeline, especially as it pertains to both Rails apps and gems (engines). The presentation aims to clarify the complexities of asset management, address common pain points, and provide practical solutions and strategies for leveraging modern asset tools in the Rails ecosystem.

Key Points Discussed

• Historical Context and Motivation
  • Early asset management involved manually loading various scripts and styles, which quickly became unmanageable and inefficient.
  • Problems like multiple HTTP requests, cache busting, and preprocessing (transpiling) led to the development of the asset pipeline and tools like Sprockets.
• The Evolving Asset Pipeline
  • Sprockets became the backbone of asset management in Rails, handling bundling, fingerprinting, and transpiling.
  • With the rise of new browser capabilities (HTTP/2) and smarter languages (modern JS, CSS), there’s been a shift toward lighter tools like Propshaft.
• Modern Alternatives and Tools
  • Introduction of Propshaft as a simpler Sprockets replacement, focusing on fingerprinting, a dev server, minimal transpiling, and configurable load paths.
  • Overview of modern asset strategies:
  • Import maps (let browsers fetch JS modules directly)
  • JS bundling/CSS bundling gems leveraging tools like ESBuild, Rollup, and Webpack
  • Third-party solutions (Vite Rails, Shakapacker)
• Best Practices for Shipping Assets in Gems
  • Demonstrates challenges for engine/library authors who do not control the host app, and thus must support a variety of build setups.
  • Three main strategies for including assets in gems:
  • Simple inclusion with import maps
  • Bundling npm dependencies directly, or letting the user pin versions
  • Creating npm packages and instructing users to use them directly
  • Addresses advanced scenarios and unorthodox solutions like writing Rake tasks to copy or symlink assets, middleware-based static asset serving, and dynamic JavaScript injection for plugin systems.
• Practical Examples
  • Case study: Building the Marksmith markdown editor as a gem with flexible asset distribution approaches
  • Real-world setup in open-source projects like AVO
• CSS Asset Management
  • Emphasizes that Propshaft simplifies CSS inclusion — just use a stylesheet link tag and optionally use @import or url() for further asset references.
• Final Takeaways
  • While asset management in Rails is complex, new tools and clear guardrails make the process manageable for both applications and engines.
  • Developers must understand multiple approaches to ensure their libraries work smoothly across a spectrum of Rails setups.

Conclusion

The talk offers a structured progression from legacy asset management practices through modern Rails solutions. Practical code snippets, pros and cons for each asset distribution method, and a focus on real-world application equip viewers to tackle asset pipeline challenges in their own Rails apps and gems.