ReactiveComponent

Reactive server-rendered components for Rails via ActionCable. Build ViewComponent components that automatically re-render on the client when data changes — no full page reloads needed.

ReactiveComponent compiles your ERB templates to JavaScript at boot time and uses ActionCable to push updates in real time.

Documentation | Quick Start | DSL Reference

Quick Example

class MessageRowComponent < ApplicationComponent
  include ReactiveComponent

  subscribes_to :message
  broadcasts stream: ->(message) { [message.recipient, :messages] }
  live_action :toggle_star
  client_state :selected, default: false

  def initialize(message:)
    @message = message
  end

  private

  def toggle_star
    @message.toggle_starred!
  end
end

<div class="message-row">
  <span><%= @message.sender.name %></span>
  <span><%= @message.subject %></span>
  <button data-action="click->reactive-renderer#performAction"
          data-reactive-renderer-action-param="toggle_star">
    <%= @message.starred? ? "Unstar" : "Star" %>
  </button>
</div>

When the message is updated anywhere in the system, the component re-renders on every connected client automatically.

Installation

Add to your Gemfile:

gem "reactive_component"

Mount the engine in your routes:

# config/routes.rb
mount ReactiveComponent::Engine => "/reactive_component"

Using esbuild, Vite, Rspack, or another bundler instead of importmap? Install the Stimulus controller from npm under the reactive_component alias:

pnpm add reactive_component@npm:@lluzak/reactive_component

See Other bundlers for details.

See the Installation guide for full setup instructions.

Features

• Declarative DSL — subscribes_to, broadcasts, live_action, client_state
• Automatic ERB-to-JS compilation — no separate client templates to maintain; compiled on Prism's own tree
• Compile-time errors, not guesses — anything the compiler can't make reactive raises CompileError naming the source
• ActionCable-powered live updates — instant re-renders when data changes
• Secure server actions — HMAC-signed tokens prevent tampering
• Client-side state — ephemeral UI state managed in the browser
• Multi-Rails support — tested against Rails 7.1, 7.2, and 8.0

How It Works

ReactiveComponent compiles your ERB templates into JavaScript render functions at boot time: Prism parses the template, and one pass over its tree lifts every Ruby expression to the server and turns the remaining skeleton — literals, conditionals, loops — into JavaScript. When a model changes:

1. after_commit callbacks (auto-wired by subscribes_to) trigger a broadcast.
2. The server evaluates only the dynamic expressions from your template and sends compact JSON data over ActionCable.
3. The client-side Stimulus controller runs the compiled JS template with the new data and updates the DOM.

No full page reload. No custom JavaScript. Your existing ERB templates are the single source of truth.

See the full architecture guide for details.

Advanced Features

• Nested components -- Render reactive components inside other reactive components. Guide
• Collection loops -- Use .each in templates with automatic per-item data extraction. Guide
• Broadcast compression -- Gzip-compress ActionCable payloads for large components. Configuration
• Notify mode -- Re-render from the server on change, and drop rows that no longer match a filtered list. Guide
• Derived entities -- Subscribe a component to an object built from several models. Guide

Development

bin/setup
bundle exec rake test
npm run test:js

Releasing

1. Bump lib/reactive_component/version.rb and package.json to the same version, and date its CHANGELOG.md heading.
2. Commit Release vX.Y.Z on main, tag vX.Y.Z, and push both.

The tag runs the Release workflow: it checks both versions match the tag, builds the gem, publishes the JS package to npm, and creates the GitHub release with the changelog section and the .gem attached. Push the gem to RubyGems yourself with gem push reactive_component-X.Y.Z.gem.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/lluzak/reactive_component.

License

The gem is available as open source under the terms of the MIT License.