hotwire

使用Hotwire(Turbo + Stimulus)构建现代Rails界面。适用场景:1)使用Turbo Drive实现页面导航和表单处理;2)使用Turbo Frames进行局部页面更新;3)使用Turbo Streams实现实时DOM更新;4)使用Stimulus控制器实现JavaScript行为;5)使用Action Cable进行WebSocket广播;6)实现任何交互式UI而不依赖重型JavaScript框架。

📖 中文导读:使用Hotwire(Turbo + Stimulus)构建现代Rails界面。适用场景:1)使用Turbo Drive实现页面导航和表单处理;2)使用Turbo Frames进行局部页面更新;3)使用Turbo Streams实现实时DOM更新;4)使用Stimulus控制器实现JavaScript行为;5)使用Action Cable进行WebSocket广播;6)实现任何交互式UI而不依赖重型JavaScript框架。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: hotwire description: "Build modern Rails interfaces with Hotwire (Turbo + Stimulus). Use when implementing: (1) Page navigation and form handling with Turbo Drive, (2) Partial page updates with Turbo Frames, (3) Real-time DOM updates with Turbo Streams, (4) JavaScript behaviors with Stimulus controllers, (5) WebSocket broadcasts with Action Cable, (6) Any interactive UI without heavy JavaScript frameworks."

Hotwire

Hotwire sends HTML over the wire instead of JSON, enabling SPA-like interactivity without JavaScript frameworks.

Decision Framework

Choose the right tool for each interaction:

Need Tool Example
Fast page navigation Turbo Drive Links, form submissions
Update one section Turbo Frame Edit-in-place, tabs, modals
Update multiple sections Turbo Stream Form creates item + clears form
Real-time updates Turbo Stream + Action Cable Chat, notifications
JavaScript behavior Stimulus Dropdowns, copy-to-clipboard

Rule of thumb: Use Turbo for server-driven updates, Stimulus for client-side behavior.

Turbo Frames Quick Reference

Wrap content in a frame to scope navigation:

<%= turbo_frame_tag @todo do %>
  <p><%= @todo.description %></p>
  <%= link_to "Edit", edit_todo_path(@todo) %>
<% end %>

Clicking "Edit" replaces only this frame with the matching frame from the response.

Lazy loading:

<%= turbo_frame_tag "sidebar", src: sidebar_path, loading: "lazy" %>

Break out of frame:

<%= link_to "Full page", path, data: { turbo_frame: "_top" } %>

See references/turbo.md for complete Turbo documentation.

Turbo Streams Quick Reference

Stream actions for DOM updates:

Action Effect
append Add to end of target
prepend Add to beginning
replace Replace entire element
update Replace innerHTML only
remove Delete element
before/after Insert adjacent

Controller response:

respond_to do |format|
  format.turbo_stream
  format.html { redirect_to @item }
end

Template (create.turbo_stream.erb):

<%= turbo_stream.append :items, @item %>
<%= turbo_stream.update :form, partial: "form" %>

Real-time broadcasts:

# In model
broadcasts_refreshes  # Simple: triggers page refresh with morphing

# Or manual:
broadcast_append_to :items, target: :items

See references/turbo.md for stream actions and broadcasting.

Stimulus Quick Reference

Controller structure:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["input", "output"]
  static values = { url: String, count: { type: Number, default: 0 } }
  static classes = ["active"]
  static outlets = ["other-controller"]

  connect() { /* called when controller connects to DOM */ }
  disconnect() { /* called when removed from DOM */ }

  // Action methods (called from data-action)
  submit() {
    this.outputTarget.textContent = this.inputTarget.value
    this.countValue++
    this.dispatch("submitted", { detail: { value: this.inputTarget.value } })
  }

  // Private methods
  #helperMethod() { }
}

HTML:

<div data-controller="example"
     data-example-url-value="/api"
     data-example-active-class="is-active">
  <input data-example-target="input" data-action="input->example#submit">
  <span data-example-target="output"></span>
</div>

Action syntax: event->controller#method

  • Default events: click for buttons, submit for forms, input for inputs
  • Modifiers: :prevent, :stop, :once, @window, @document
  • Key filters: keydown.enter->controller#method

See references/stimulus.md for complete reference.

Rails Helpers

Turbo Frame tag:

<%= turbo_frame_tag @model %>
<%= turbo_frame_tag @model, :section %>
<%= turbo_frame_tag "custom_id", src: path, loading: "lazy" %>

Turbo Stream tag:

<%= turbo_stream.append :target, partial: "item", locals: { item: @item } %>
<%= turbo_stream.replace @model %>
<%= turbo_stream.remove @model %>

Stimulus controller generator:

bin/rails generate stimulus controller_name

See references/rails-integration.md for helpers and setup.