hotwire-patterns（热线模式）

Hotwire Patterns for Rails

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

Quick Reference

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

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 = ""
    }
  }
}

Key: disconnect() must unsubscribe to prevent leaked subscriptions during Turbo navigation.

Critical Gotchas

Missing 422 Status Code

Turbo will NOT render form error responses unless the server returns status::unprocessable_entity (422). This is the #1 Hotwire debugging issue:

# WRONG: Turbo ignores this response
format.html { render :new }

# RIGHT: Turbo processes the response
format.html { render :new, status: :unprocessable_entity }

Frame ID Mismatch (Silent Failure)

If the response HTML does not contain a <turbo-frame> with a matching id, nothing happens -- no error, no update. Debug with:

• Browser console: look for "Response has no matching " warning
• Verify dom_id(@record) produces the same ID on both pages
• Check that the edit/show view wraps content in the same frame tag

Broadcasting Without Scoping

# WRONG: every connected user sees every message
after_create_commit { broadcast_prepend_to "messages" }

# RIGHT: scope to the relevant stream
after_create_commit -> { broadcast_prepend_to(room, :messages) }
after_create_commit -> { broadcast_prepend_to(user, :notifications) }  # per-user

Anti-Patterns

Progressive Enhancement Checklist

Before shipping any Hotwire feature, verify:

• Core functionality works with Turbo Drive disabled (data-turbo="false")
• Forms submit successfully without JS (standard HTML submission)
• Links navigate to full pages without Turbo Frames
• Stimulus controllers degrade gracefully (content visible without JS)
• data-turbo-permanent preserves media players, ActionCable connections across navigation
• data-turbo="false" on file downloads and external links

Output Format

When analyzing or creating Hotwire components, provide:

1. Stimulus controller (JS) with targets, values, classes
2. View partial (ERB) with proper data attributes
3. Controller action with turbo_stream response format
4. Model broadcasts if real-time updates needed
5. Cable subscription if ActionCable integration required