Add first class component cache by reeganviljoen · Pull Request #2126 · ViewComponent/view_component

reeganviljoen · 2024-10-08T20:00:40Z

closes #234

What are you trying to accomplish?

Add experimental fragment caching for ViewComponent that is true to the ViewComponent ethos, namely:

caching remains component-local (no hidden global state required to work)
caching that can easily be debugged with standard debugging tools like breakpoints

What approach did you choose and why?

I chose to add an opt-in caching API:

ViewComponent::Cacheable + a cache_on macro that declares which instance methods contribute to the cache key
cache keys include component identity + template identity (variant/format) + declared dependencies (via ActiveSupport::Cache.expand_cache_key) + a component digest
the component digest invalidates cached output when the component’s source changes (Ruby file, templates, i18n sidecars) and when rendered child ViewComponents change
template dependency extraction compiles templates to Ruby and uses Prism to find render dependencies
- ERB uses stdlib ERB::Compiler (no Temple)
- Slim/Haml are loaded lazily and only when those handlers are used

Anything you want to highlight for special attention from reviewers?

This is intentionally opt-in (global opt-in via require "view_component/fragment_caching" or per-component include ViewComponent::Cacheable)
Added integration coverage proving parent cache invalidates when a child component template changes
cache_on supports private methods and uses Rails cache key expansion for dependency values
Known limitation: partial/layout string dependencies are not currently included in the digest (workaround: bump RAILS_CACHE_ID/RAILS_APP_VERSION on deploy)
Follow-ups can extend the API (procs, conditionals/options, broader dependency coverage)

reeganviljoen · 2024-10-15T19:32:51Z

@joelhawksley @Spone @camertron I would appreciate any thoughts on this.

joelhawksley

@reeganviljoen THANK YOU for taking a crack at building something functional to address the long-overdue need for caching in ViewComponent.

To be honest with you, I have not used caching in Rails nearly enough to feel like I can properly assess this PR in terms of how it would integrate with the existing mental model of caching in Rails. I'm happy to learn that context, but I won't have the space to do so for at least a couple of weeks.

@Spone @boardfish have y'all done much with Rails' caching? @reeganviljoen if you know of anyone else in the community who would be a good reviewer here, I'd be happy to have them.

reeganviljoen · 2024-10-16T04:28:05Z

@reeganviljoen THANK YOU for taking a crack at building something functional to address the long-overdue need for caching in ViewComponent.

To be honest with you, I have not used caching in Rails nearly enough to feel like I can properly assess this PR in terms of how it would integrate with the existing mental model of caching in Rails. I'm happy to learn that context, but I won't have the space to do so for at least a couple of weeks.

@Spone @boardfish have y'all done much with Rails' caching? @reeganviljoen if you know of anyone else in the community who would be a good reviewer here, I'd be happy to have them.

@joelhawksley I really aprreciate the honesty, I will see if I can find anyone with cache experience to take a crack at reviewing this ❤️

boardfish · 2024-10-16T08:09:41Z

@joelhawksley Afraid it's not something I've really interacted with directly until now, sorry! I'd be coming from a similar place. Great to see @reeganviljoen working at it, though ✨

JWShuff

Reegan, really excited to see this. I'm going to take a shot at adapting our gem spec suite to your fork and open a PR at your fork with those specs by way of giving us a place to start that gives us the most cache functionality we can get.

JWShuff · 2024-11-14T18:06:40Z

    include ViewComponent::Slotable
    include ViewComponent::Translatable
    include ViewComponent::WithContentHelper
+    include ViewComponent::Cacheable


Suggestion, nitpick and nonblocking: Can we slide this in alphabetically above? I'd think it'd be ~ line 32

JWShuff · 2024-11-14T19:05:53Z

+      __vc_cache_dependencies.push(*args)
+    end
+
+    def inherited(child)


We took this for a spin in a few cases of our cached partials and view components that we are familiar with and largely it works for the base cases. This is working to correctly bust a cached VC when it changes or things in the render path 'above' (partials or VCs) it change.

What we aren't seeing is when a VC renders another VC or partial as a child that downstream changes of the cached VC pick up changes and handle it. I'm going to fork your branch and offer some test cases based on an approach we use in the vc fragment caching gem (what we're currently solving this with)

Effectively we want some way for a child partial or VC change (in either the .rb or template) to bust the cached parent.

@JWShuff like touch: true in rails ?

also big thanks for testing it, I can look at adding the touch true thing later this week

@reeganviljoen I'd expect us to test this with changes to child partials.

JWShuff

Added a hypothetical approach to an integration test for the behavior.

JWShuff · 2024-11-14T22:03:20Z

@reeganviljoen I am not a git-wizard, much to my eternal shame, but I set up a fork and adjusted the spec approach here to use the integration examples/controllers to assert the behavior. Feel free to take, leave, or otherwise.

JWShuff#1

There's a wider challenge around partial/template digesting, and on a quiet day I'll port our spec suite over to the VC style and get it implemented so we have all the permutations we know of that need to cache appropriately.

reeganviljoen · 2024-11-19T20:19:14Z

@JWShuff I investigated a few of your suggestions, added a few, thanks, and others I am struggling with
luckily I think these aren't required for the initial feature and are more nice to haves that can be implemented in another pr(child cache busting)

reeganviljoen · 2024-11-19T20:19:55Z

@joelhawksley with a live use case tested how do you feel about this now

reeganviljoen · 2026-02-13T13:13:11Z

@joelhawksley im not sure if thd primer failure is related but everything I feel is done, I would appreciate a review when ever you can

joelhawksley

Getting closer! Thank you for your hard work ❤️

joelhawksley · 2026-02-13T22:35:10Z

+Caching is experimental.
+
+To enable caching, include `ViewComponent::ExperimentallyCacheable`.
+
+Components implement caching by marking dependencies using `cache_on`:


Suggested change

Caching is experimental.

To enable caching, include `ViewComponent::ExperimentallyCacheable`.

Components implement caching by marking dependencies using `cache_on`:

To enable caching, include `ViewComponent::ExperimentallyCacheable` and declare dependencies by passing method names (private methods allowed) to `cache_on`:

Is it true that one must call cache_on? What if you don't?

joelhawksley · 2026-02-13T22:36:16Z

+<p><%= "#{foo} #{bar}" %></p>
+```
+
+`cache_on` accepts method names. Returned values are expanded via `ActiveSupport::Cache.expand_cache_key`, so Active Record models, `GlobalID`, arrays, and plain strings work as expected.


Suggested change

`cache_on` accepts method names. Returned values are expanded via `ActiveSupport::Cache.expand_cache_key`, so Active Record models, `GlobalID`, arrays, and plain strings work as expected.

Returned values are expanded via `ActiveSupport::Cache.expand_cache_key`, so Active Record models, `GlobalID`, arrays, and plain strings work as expected.

joelhawksley · 2026-02-13T22:37:06Z

+Methods listed in `cache_on` may be private.
+


Suggested change

Methods listed in `cache_on` may be private.

joelhawksley · 2026-02-13T22:39:25Z

+
+Methods listed in `cache_on` may be private.
+
+The cache key includes a digest of component source (Ruby + templates + i18n sidecars) and rendered child ViewComponents.


Suggested change

The cache key includes a digest of component source (Ruby + templates + i18n sidecars) and rendered child ViewComponents.

The cache key includes a digest of the component, its sidecar files, and with ViewComponents rendered by the component.

joelhawksley · 2026-02-13T22:40:40Z

+
+The cache key includes a digest of component source (Ruby + templates + i18n sidecars) and rendered child ViewComponents.
+
+Partial/layout string dependencies aren't currently included in the digest, to invalidate the cache on deploy modify `RAILS_CACHE_ID`/`RAILS_APP_VERSION`.


Suggested change

Partial/layout string dependencies aren't currently included in the digest, to invalidate the cache on deploy modify `RAILS_CACHE_ID`/`RAILS_APP_VERSION`.

_Warning: changes to partial and layout string dependencies will not invalidate the cache. Modify `RAILS_CACHE_ID` or `RAILS_APP_VERSION` instead._

joelhawksley · 2026-02-18T18:02:54Z

+      end
+    end
+
+    def file_contents(path)


Suggested change

def file_contents(path)

def cached_file_contents(path)

joelhawksley · 2026-02-18T18:03:23Z

+  module CachingRegistry
+    extend self
+
+    def caching?


I don't see this method called or tested anywhere. Do we need it?

joelhawksley · 2026-02-18T18:06:24Z

+
+    def template_fragment(cache_key, safe_call)
+      if (content = read_fragment(cache_key))
+        @view_renderer.cache_hits[@current_template&.virtual_path] = :hit if defined?(@view_renderer)


Should we always be recording hits/misses, or only when instrumentation is enabled?

joelhawksley · 2026-02-18T18:07:46Z

+    end
+
+    def combined_fragment_cache_key(key)
+      cache_key = [:view_component, ENV["RAILS_CACHE_ID"] || ENV["RAILS_APP_VERSION"], key]


I believe you've implied that changing either ENV would work:

Suggested change

cache_key = [:view_component, ENV["RAILS_CACHE_ID"] || ENV["RAILS_APP_VERSION"], key]

cache_key = [:view_component, ENV["RAILS_CACHE_ID"], ENV["RAILS_APP_VERSION"], key]

Do we have a test for ensuring that changing each busts the cache?

joelhawksley · 2026-02-18T18:12:41Z

+require "digest"
+require "view_component/template_dependency_extractor"
+
+module ViewComponent


I wonder how much of this work we could do at compile time, especially when eager loading is enabled. I believe everything except for the value(s) of cache_on should be stable at that point.

reeganviljoen · 2026-06-14T13:50:53Z

@joelhawksley and everyone who has reviewed or tested this so far, I have come back to this with a few fixes addressing the latest comments.

The main changes are:

moved the API to cache do ... end and updated the docs around that
kept caching opt-in per component while experimental
switched the fragment reads/writes to go through Rails fragment caching APIs
added sidecar_templates / sidecar_translations
simplified the digestor and added ViewComponent::CacheDigestor.digest
made cache hit/miss recording respect the instrumentation setting
added/precomputed the component digest when template caching is enabled
added coverage for ERB, Slim, Haml, and Jbuilder template handlers
kept the partial/layout string dependency limitation documented and covered by tests

I think this now addresses the comments raised here, but I would really appreciate another pass before we try to land it.

@JWShuff @tmaier if either of you have time to test this against real cached component use cases again, that would be especially helpful.

Thanks again everyone for all the review and patience on this.

…into rv_add_component_caching # Conflicts: # .tool-versions # Gemfile.lock # docs/CHANGELOG.md # gemfiles/rails_main.gemfile.lock # test/sandbox/test/rendering_test.rb

…ching

…v_add_component_caching

joelhawksley · 2026-07-23T17:25:41Z

@reeganviljoen when you have some time, I'd be curious about your thoughts on @timburgan's PR ❤️

reeganviljoen · 2026-07-24T15:02:30Z

@joelhawksley I have left a small comment on @timburgen's pr, the preliminary review I did leads me to believe it would be a good course of action to bring his commits in here

The cache digestor reached into ActionView::Template.template_handler_extensions and hardcoded %w[yml yaml], the latter duplicating Translatable's TRANSLATION_EXTENSIONS. Expose sidecar_templates (Base) and sidecar_translations (Translatable) so the handler-extension coupling lives in one auditable place and the translation list can't drift from i18n loading. Addresses review feedback on the PR (sidecar_templates/sidecar_translations).

cache_hits is :nodoc: and only annotates the render log; feature-detect it with respond_to? so a future Rails change can't raise during caching. The supported hit/miss signal remains the read_fragment/write_fragment ActiveSupport notifications, which fire regardless.

The bare rescue turned any ActionView::Template/handler-call signature break into a silent nil, which degrades to empty dependencies and stale caches. Capture the error and emit template_ast_build_failed.view_component instrumentation, and add per-handler canary tests (erb/slim/haml) so an upgrade break fails loudly in CI.

cache_if evaluated Symbol/String conditions with public_send, so the documented example (cache_if :cacheable? with a private cacheable?) crashed at render with NoMethodError. Use send, consistent with how the cache block itself is evaluated via instance_exec. The existing cache_if test now uses a private method, and a positive test covers a private condition that enables caching.

The cache key was composed only of the component digest and the cache block's dependencies, so a component with sidecar translations served the cached fragment from whichever locale rendered first (e.g. English output for a French request). Add I18n.locale to the key and cover it with a translatable, cacheable component that must render the correct language per locale.

Dependency extraction ran only over template source, so a child rendered from a Ruby method (e.g. a helper called from the template) was not a tracked dependency and changes to it did not bust the parent digest. Also scan the component's own Ruby source for component renders (render Foo.new) and recurse, so indirect children invalidate the parent like template-level renders do.

__vc_cache_key_block/__vc_cache_if are class_attributes, which already inherit. The extra inherited hook eagerly copied the parent's then-current value into each subclass, so declaring cache on a parent AFTER a subclass was defined left the subclass with a stale nil and it silently would not cache. Rely on class_attribute inheritance instead.

Cover def-call components, ActiveRecord-like models (hit + invalidate on update), child .rb changes, indirectly-rendered children, cyclic/self-referential digest termination, variant isolation, HTML-safety round-trip, and cache-block inheritance ordering.

@Private

Condense the rationale comments on the AST-build rescue, cache_hits guard, and extract_component_renders to match the terse style of the surrounding internal classes. Mark sidecar_templates/sidecar_translations @Private: both are only called cross-class by the digestor and translation loader, so they stay Ruby-public but out of the documented API surface.

reeganviljoen changed the title ~~add component controlled cache~~ Add First class component cache Oct 8, 2024

reeganviljoen changed the title ~~Add First class component cache~~ Add first class component cache Oct 8, 2024

reeganviljoen requested a review from joelhawksley October 8, 2024 20:03

reeganviljoen force-pushed the rv_add_component_caching branch from 7544079 to 7533a9c Compare October 10, 2024 15:21

joelhawksley reviewed Oct 15, 2024

View reviewed changes

mikodagatan reviewed Oct 16, 2024

View reviewed changes