docs/pro/fragment-caching.md
Fragment caching is a React on Rails Pro feature that caches the complete rendered output of a React component — including the cost of computing props from the database, serializing them to JSON, and evaluating JavaScript. On a cache hit, none of that work happens.
Route map: Start at React on Rails Pro if you're choosing a path. This page is the canonical fragment caching overview; for the lower-level cache settings and tradeoffs, see the SSR caching guide and Pro configuration docs.
Every server-rendered React component involves multiple expensive steps:
Fragment caching skips all four steps when the cache is warm. This is different from prerender caching, which only skips step 3.
| Prerender Caching | Fragment Caching | |
|---|---|---|
| What it caches | JavaScript evaluation result | Everything: props assembly, serialization, JS evaluation, HTML output |
| Setup effort | One config line | Choose cache keys, pass props as a block |
| Skips prop evaluation? | No | Yes |
| Best for | Quick win with minimal code changes | Maximum performance on high-traffic pages |
Recommendation: Start with prerender caching (config.prerender_caching = true), then add fragment caching to your most expensive components.
Use cached_react_component instead of react_component. The key differences:
cache_key (same as Rails fragment caching)<%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do
some_slow_method_that_returns_props
end %>
A cached_react_component_hash variant is also available for cases where you need to extract metadata (like <title>) from the rendered output.
Every deploy creates new cache keys for prerendered components (because the server bundle digest is included in the cache key when prerender: true). For client-only cached components, version your own cache key to invalidate on deploy. To avoid a storm of cold-cache misses under live traffic, warm your highest-traffic pages in background jobs immediately after deploy.
See the Cache Warming section in the caching guide for implementation patterns and real-world results.