hotwire-patterns

Hotwire Patterns for Rails

Analyze and recommend Stimulus + Turbo patterns for modern, interactive Rails applications.

Applies on the html delivery axis (Axis B, rails-stack-profiles). An api-delivery project has no server-rendered views and does not use Hotwire — use rails-api-patterns instead.

Quick Reference

Component	Use When
Stimulus	Adding JS behaviors to server-rendered HTML
Turbo Drive	Default for all links/forms (no config needed)
Turbo Frames	Update a section without full reload
Turbo Streams	Update multiple DOM elements from one response
ActionCable + Streams	Push real-time updates to connected clients

Supporting Documentation

• stimulus.md - Stimulus integration patterns and production gotchas
• turbo.md - Turbo Frames, Streams, and version-aware patterns

Core Philosophy

HTML over the wire: Send HTML from the server, not JSON. JavaScript enhances server-rendered HTML.

1. Progressive enhancement: Works without JS, better with it
2. Server-first: Business logic stays on the server
3. Minimal JavaScript: Just enough JS to make HTML interactive
4. No client-side state: Server is the source of truth

Decision Guide: Frames vs Streams

Scenario	Use	Why
Edit-in-place	Frame	Scoped navigation, replaces itself
Form creates item + updates counter	Stream	Multiple targets from one response
Lazy sidebar	Frame with loading: :lazy	Deferred load, single target
Real-time chat	ActionCable + Stream	Push from server to all clients
Tabs/pagination	Frame	Scoped replacement
Flash + content update	Stream	Two targets: flash div + content

ActionCable + Stimulus Integration

This pattern is non-obvious -- it wires a Stimulus controller to an ActionCable subscription, giving you lifecycle-managed real-time behavior:

// app/javascript/controllers/chat_controller.js
import { Controller } from "@hotwired/stimulus"
import consumer from "../channels/consumer"

export default class extends Controller {
  static targets = ["messages", "input"]
  static values = { roomId: Number }

  connect() {
    this.subscription = consumer.subscriptions.create(
      { channel: "ChatChannel", room_id: this.roomIdValue },
      { received: (data) => this.messagesTarget.insertAdjacentHTML("beforeend", data.html) }
    )
  }
  disconnect() { this.subscription?.unsubscribe() }
  send(e) {
    e.preventDefault()
    if (this.inputTarget.value.trim()) {
      this.subscription.send({ message: this.inputTarget.value })
      this.inputTarget.value = ""
    }
  }
}