Add first class component cache

docs/CHANGELOG.md

@@ -10,11 +10,15 @@ nav_order: 6
 
 ## main
 
+* Add experimental support for caching.
+
+    *Reegan Viljoen*
+
 * Introduce component-local config and migrate `strip_trailing_whitespace` to use it under the hood.
 
     *Simon Fish*
 
-* Add docs about Slack channel in Ruby Central workspace. (Join us! #oss-view-component). Email [email protected] for an invite.
+* Add docs about Slack channel in Ruby Central workspace. (Join us! #oss-view-component). Email <[email protected]> for an invite.
 
     *Joel Hawksley
 
@@ -1470,7 +1474,7 @@ Run into an issue with this release? [Let us know](https://github.com/ViewCompon
 
     *Joel Hawksley*
 
-* The ViewComponent team at GitHub is hiring! We're looking for a Rails engineer with accessibility experience: [https://boards.greenhouse.io/github/jobs/4020166](https://boards.greenhouse.io/github/jobs/4020166). Reach out to [email protected] with any questions!
+* The ViewComponent team at GitHub is hiring! We're looking for a Rails engineer with accessibility experience: [https://boards.greenhouse.io/github/jobs/4020166](https://boards.greenhouse.io/github/jobs/4020166). Reach out to <[email protected]> with any questions!
 
 * The ViewComponent team is hosting a happy hour at RailsConf. Join us for snacks, drinks, and stickers: [https://www.eventbrite.com/e/viewcomponent-happy-hour-tickets-304168585427](https://www.eventbrite.com/e/viewcomponent-happy-hour-tickets-304168585427)
 
@@ -2234,7 +2238,7 @@ Run into an issue with this release? [Let us know](https://github.com/ViewCompon
 
     *Matheus Richard*
 
-* Are you interested in building the future of ViewComponent? GitHub is looking to hire a Senior Engineer to work on Primer ViewComponents and ViewComponent. Apply here: [US/Canada](https://github.com/careers) / [Europe](https://boards.greenhouse.io/github/jobs/3132294). Feel free to reach out to [email protected] with any questions.
+* Are you interested in building the future of ViewComponent? GitHub is looking to hire a Senior Engineer to work on Primer ViewComponents and ViewComponent. Apply here: [US/Canada](https://github.com/careers) / [Europe](https://boards.greenhouse.io/github/jobs/3132294). Feel free to reach out to <[email protected]> with any questions.
 
     *Joel Hawksley*
 
@@ -2252,7 +2256,7 @@ Run into an issue with this release? [Let us know](https://github.com/ViewCompon
 
 ## 2.31.0
 
-_Note: This release includes an underlying change to Slots that may affect incorrect usage of the API, where Slots were set on a line prefixed by `<%=`. The result of setting a Slot shouldn't be returned. (`<%`)_
+*Note: This release includes an underlying change to Slots that may affect incorrect usage of the API, where Slots were set on a line prefixed by `<%=`. The result of setting a Slot shouldn't be returned. (`<%`)*
 
 * Add `#with_content` to allow setting content without a block.
 
@@ -2700,7 +2704,7 @@ _Note: This release includes an underlying change to Slots that may affect incor
 
   * The gem name is now `view_component`.
   * ViewComponent previews are now accessed at `/rails/view_components`.
-  * ViewComponents can _only_ be rendered with the instance syntax: `render(MyComponent.new)`. Support for all other syntaxes has been removed.
+  * ViewComponents can *only* be rendered with the instance syntax: `render(MyComponent.new)`. Support for all other syntaxes has been removed.
   * ActiveModel::Validations have been removed. ViewComponent generators no longer include validations.
   * In Rails 6.1, no monkey patching is used.
   * `to_component_class` has been removed.

docs/guide/caching.md

@@ -0,0 +1,42 @@
+---
+layout: default
+title: Caching
+parent: How-to guide
+---
+
+# Caching
+
+Experimental
+{: .label }
+
+Components can implement caching by marking the depndencies that a digest can be built om using the cache_on macro, like so:
+
+```ruby
+class CacheComponent < ViewComponent::Base
+  include ViewComponent::Cacheable
+
+  cache_on :foo, :bar
+  attr_reader :foo, :bar
+
+  def initialize(foo:, bar:)
+    @foo = foo
+    @bar = bar
+  end
+end
+```
+
+```erb
+<p><%= view_cache_dependencies %></p>
+
+<p><%= Time.zone.now %>"></p>
+<p><%= "#{foo} #{bar}" %></p>
+```
+
+will result in:
+
+```html
+<p>foo-bar</p>
+
+<p>2025-03-27 16:46:10 UTC</p>
+<p> foo bar</p>
+```

lib/view_component/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "action_view"
+require "view_component/cacheable"
 require "active_support/configurable"
 require "view_component/collection"
 require "view_component/compile_cache"
@@ -111,12 +112,10 @@ def render_in(view_context, &block)
 
       if render?
         rendered_template = render_template_for(@__vc_variant, __vc_request&.format&.to_sym).to_s
-
-        # Avoid allocating new string when output_preamble and output_postamble are blank
-        if output_preamble.blank? && output_postamble.blank?
-          rendered_template
+        if respond_to?(:__vc_render_cacheable)
+          __vc_render_cacheable(rendered_template)
         else
-          safe_output_preamble + rendered_template + safe_output_postamble
+          __vc_render_template(rendered_template)
         end
       else
         ""
@@ -271,6 +270,18 @@ def view_cache_dependencies
       []
     end
 
+    # For handling the output_preamble and output_postamble
+    #
+    # @private
+    def __vc_render_template(rendered_template)
+      # Avoid allocating new string when output_preamble and output_postamble are blank
+      if output_preamble.blank? && output_postamble.blank?
+        rendered_template
+      else
+        safe_output_preamble + rendered_template + safe_output_postamble
+      end
+    end
+
     # For caching, such as #cache_if
     #
     # @private
@@ -293,6 +304,13 @@ def __vc_request
       @__vc_request ||= controller.request if controller.respond_to?(:request)
     end
 
+    # For use in caching
+    #
+    # @private
+    def __vc_format
+      __vc_request&.format&.to_sym
+    end
+
     # The content passed to the component instance as a block.
     #
     # @return [String]

lib/view_component/cache_digestor.rb

@@ -0,0 +1,19 @@
+# # frozen_string_literal: true
+
+module ViewComponent
+  class CacheDigestor
+    @@digest_mutex = Mutex.new
+
+    class << self
+      def digest(name:, finder:, format: nil, dependencies: nil)
+        if dependencies.nil? || dependencies.empty?
+          cache_key = "#{name}.#{format}"
+        else
+          dependencies_suffix = dependencies.flatten.tap(&:compact!).join(".")
+          cache_key = "#{name}.#{format}.#{dependencies_suffix}"
+        end
+        cache_key
+      end
+    end
+  end
+end

lib/view_component/cache_registry.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module CachingRegistry
+    extend self
+
+    def caching?
+      ActiveSupport::IsolatedExecutionState[:view_component_caching] ||= false
+    end
+
+    def track_caching
+      caching_was = ActiveSupport::IsolatedExecutionState[:view_component_caching]
+      ActiveSupport::IsolatedExecutionState[:action_view_caching] = true
+
+      yield
+    ensure
+      ActiveSupport::IsolatedExecutionState[:view_component_caching] = caching_was
+    end
+  end
+end

lib/view_component/cacheable.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "set"
+require "view_component/cache_registry"
+require "view_component/cache_digestor"
+
+module ViewComponent::Cacheable
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :__vc_cache_dependencies, default: Set[:format, :__vc_format, :identifier]
+
+    # For caching, such as #cache_if
+    #
+    # @private
+    def view_cache_dependencies
+      return if __vc_cache_dependencies.blank? || __vc_cache_dependencies.none? || __vc_cache_dependencies.nil?
+
+      computed_view_cache_dependencies = __vc_cache_dependencies.map { |dep| if respond_to?(dep) then public_send(dep) end }
+      combined_fragment_cache_key(ActiveSupport::Cache.expand_cache_key(computed_view_cache_dependencies))
+    end
+
+    # Render component from cache if possible
+    #
+    # @private
+    def __vc_render_cacheable(rendered_template)
+      if __vc_cache_dependencies != [:format, :__vc_format]
+        ViewComponent::CachingRegistry.track_caching do
+          template_fragment(rendered_template)
+        end
+      else
+        __vc_render_template(rendered_template)
+      end
+    end
+
+    def template_fragment(rendered_template)
+      if content = read_fragment(rendered_template)
+        @view_renderer.cache_hits[@current_template&.virtual_path] = :hit if defined?(@view_renderer)
+        content
+      else
+        @view_renderer.cache_hits[@current_template&.virtual_path] = :miss if defined?(@view_renderer)
+        write_fragment(rendered_template)
+      end
+    end
+
+    def read_fragment(rendered_template)
+      Rails.cache.fetch(component_digest)
+    end
+
+    def write_fragment(rendered_template)
+      content = __vc_render_template(rendered_template)
+      Rails.cache.fetch(component_digest) do
+        content
+      end
+      content
+    end
+
+    def combined_fragment_cache_key(key)
+      cache_key = [:view_component, ENV["RAILS_CACHE_ID"] || ENV["RAILS_APP_VERSION"], key]
+      cache_key.flatten!(1)
+      cache_key.compact!
+      cache_key
+    end
+
+    def component_digest
+      component_name = self.class.name.demodulize.underscore
+      ViewComponent::CacheDigestor.digest(name: component_name, format: format, finder: @lookup_context, dependencies: view_cache_dependencies)
+    end
+  end
+
+  class_methods do
+    # For caching the component
+    def cache_on(*args)
+      __vc_cache_dependencies.merge(args)
+    end
+
+    def inherited(child)
+      child.__vc_cache_dependencies = __vc_cache_dependencies.dup
+
+      super
+    end
+  end
+end

test/sandbox/app/components/cache_component.html.erb

@@ -0,0 +1,2 @@
+<p class='cache-component__cache-key'><%= view_cache_dependencies %></p>
+<p class='cache-component__cache-message' data-time=data-time="<%= Time.zone.now %>"><%= "#{foo} #{bar}" %></p>

test/sandbox/app/components/cache_component.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class CacheComponent < ViewComponent::Base
+  include ViewComponent::Cacheable
+
+  cache_on :foo, :bar
+
+  attr_reader :foo, :bar
+
+  def initialize(foo:, bar:)
+    @foo = foo
+    @bar = bar
+  end
+end

test/sandbox/app/components/inherited_cache_component.html.erb

@@ -0,0 +1,3 @@
+<p class='cache-component__cache-key'><%= view_cache_dependencies %></p>
+
+<p class='cache-component__cache-message' data-time=data-time="<%= Time.zone.now %>"><%= "#{foo} #{bar}" %></p>

test/sandbox/app/components/inherited_cache_component.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class InheritedCacheComponent < CacheComponent
+  def initialize(foo:, bar:)
+    super
+  end
+end

test/sandbox/app/components/no_cache_component.html.erb

@@ -0,0 +1,3 @@
+<p class='cache-component__cache-key'><%= view_cache_dependencies %></p>
+
+<p class='cache-component__cache-message' data-time=data-time="<%= Time.zone.now %>"><%= "#{foo} #{bar}" %></p>

test/sandbox/app/components/no_cache_component.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class NoCacheComponent < ViewComponent::Base
+  include ViewComponent::Cacheable
+
+  attr_reader :foo, :bar
+
+  def initialize(foo:, bar:)
+    @foo = foo
+    @bar = bar
+  end
+end

test/sandbox/app/controllers/integration_examples_controller.rb

@@ -11,6 +11,12 @@ def controller_inline
     render(ControllerInlineComponent.new(message: "bar"))
   end
 
+  def controller_inline_cached
+    foo = params[:foo] || "foo"
+    bar = params[:bar] || "bar"
+    render(CacheComponent.new(foo: foo, bar: bar))
+  end
+
   def controller_inline_with_block
     render(ControllerInlineWithBlockComponent.new(message: "bar").tap do |c|
       c.with_slot(name: "baz")

test/sandbox/config/routes.rb

@@ -11,6 +11,7 @@
   get :inline_products, to: "integration_examples#inline_products"
   get :cached, to: "integration_examples#cached"
   get :render_check, to: "integration_examples#render_check"
+  get :controller_inline_cached, to: "integration_examples#controller_inline_cached"
   get :controller_inline, to: "integration_examples#controller_inline"
   get :controller_inline_with_block, to: "integration_examples#controller_inline_with_block"
   get :controller_inline_baseline, to: "integration_examples#controller_inline_baseline"

test/sandbox/test/rendering_test.rb

@@ -19,7 +19,7 @@ def test_render_inline_allocations
       if Rails.version.to_f < 8.0
         {"3.3.8" => 128, "3.3.0" => 140, "3.2.8" => 126, "3.1.7" => 126, "3.0.7" => 135}
       elsif Rails.version.split(".").first(2).map(&:to_i) == [8, 0]
-        {"3.5.0" => 121, "3.4.3" => 125, "3.3.8" => 137}
+        {"3.5.0" => 121, "3.4.3" => 125, "3.3.8" => 138}
       else
         {"3.4.3" => 123}
       end
@@ -1260,4 +1260,34 @@ def test_render_anonymous_component_without_template
       render_inline(mock_component.new)
     end
   end
+
+  def test_cache_component
+    return if Rails.version < "7.0"
+
+    component = CacheComponent.new(foo: "foo", bar: "bar")
+    render_inline(component)
+
+    assert_selector(".cache-component__cache-key", text: component.view_cache_dependencies)
+    assert_selector(".cache-component__cache-message", text: "foo bar")
+
+    render_inline(CacheComponent.new(foo: "foo", bar: "bar"))
+
+    assert_selector(".cache-component__cache-key", text: component.view_cache_dependencies)
+
+    new_component = CacheComponent.new(foo: "foo", bar: "baz")
+    render_inline(new_component)
+
+    assert_selector(".cache-component__cache-key", text: new_component.view_cache_dependencies)
+    assert_selector(".cache-component__cache-message", text: "foo baz")
+  end
+
+  def test_no_cache_compoennt
+    return if Rails.version < "7.0"
+
+    component = NoCacheComponent.new(foo: "foo", bar: "bar")
+    render_inline(component)
+
+    assert_selector(".cache-component__cache-key", text: component.view_cache_dependencies)
+    assert_selector(".cache-component__cache-message", text: "foo bar")
+  end
 end