name: rails-hotwire description: Ruby on Rails Hotwire 最佳实践，用于使用 Turbo Drive、Turbo Frames、Turbo Streams、Turbo 8 形态变换和 Stimulus 控制器构建交互式应用。此技能应用于编写、审查或重构基于 Hotwire 的 Rails 代码，以确保导航、部分页面更新、实时广播、形态变换、Stimulus 控制器设计、错误处理和渐进增强的最佳模式。触发任务涉及 Turbo Frames、Turbo Streams、Turbo Drive、广播、形态变换、Stimulus 控制器、ActionCable、turbo_stream_from、turbo_frame_tag、data-controller、data-action 或 Hotwire 性能。与 rails-dev、rails-testing、rails-design-system、ruby-optimise 和 ruby-refactor 技能互补。

社区 Rails Hotwire 最佳实践

用于使用 Hotwire（Turbo + Stimulus）构建交互式 Rails 应用的全面指南，由社区维护。包含 9 个类别中的 53 条规则，按影响优先级排序，以指导自动化重构和代码生成。遵循 DHH “一人框架” 哲学：服务器渲染 HTML，Turbo 使其感觉像单页应用，Stimulus 在需要时添加 JavaScript 点缀。

何时应用

参考这些指南当：

配置 Turbo Drive 导航、预取和缓存行为
添加 Turbo Frames 用于部分页面更新和延迟加载
交付 Turbo Streams 用于精确 DOM 变更
通过 ActionCable 广播实时更新
启用 Turbo 8 形态变换用于页面刷新
编写 Stimulus 控制器用于客户端行为
处理 Turbo 导航、帧和 WebSocket 连接中的错误
在 Drive、Frames、Streams、形态变换和 Stimulus 之间选择
在系统和集成测试中测试 Hotwire 交互

按优先级分类的规则类别

优先级	类别	影响	前缀
1	导航与 Drive	关键	`drive-`
2	Turbo Frames	关键	`frame-`
3	Turbo Streams	高	`stream-`
4	广播与实时	高	`bcast-`
5	形态变换与页面刷新	高	`morph-`
6	性能优化	中高	`perf-`
7	Stimulus 模式	中高	`stim-`
8	架构决策	中	`arch-`
9	测试 Hotwire	中	`test-`

快速参考

1. 导航与 Drive（关键）

drive-prefetch-links - 启用链接预取以实现即时导航
drive-form-submissions - 使用 Turbo Drive 进行表单提交
drive-visit-actions - 使用访问操作控制历史记录
drive-cache-control - 为预览页面配置 Turbo 缓存
drive-selective-disable - 在不兼容页面上禁用 Turbo Drive
drive-progress-bar - 自定义 Turbo 进度条
drive-confirm-dialog - 使用 data-turbo-confirm 进行破坏性操作确认
drive-error-recovery - 优雅处理 Turbo 导航和获取错误

2. Turbo Frames（关键）

frame-lazy-loading - 延迟帧加载直到视口进入
frame-scope-navigation - 在帧内限定导航范围
frame-src-navigation - 使用 src 获取动态帧内容
frame-break-out - 处理帧跳出以进行重定向
frame-promote-visits - 将帧导航提升为页面访问
frame-dom-id - 使用 dom_id 进行帧标识
frame-empty-state - 提供有意义的帧加载状态

3. Turbo Streams（高）

stream-progressive-enhance - 始终为流提供 HTML 后备
stream-action-selection - 为 DOM 变更选择正确的流操作
stream-multi-target - 使用目标进行多元素更新
stream-http-delivery - 通过 HTTP 交付流以响应表单
stream-websocket-source - 在主体中连接 WebSocket 源
stream-custom-actions - 注册自定义流操作以进行复杂 DOM 更新

4. 广播与实时（高）

bcast-model-broadcasts - 使用 broadcasts_refreshes 进行简单模型更新
bcast-debounce-n1 - 防抖广播以防止 N+1 广播风暴
bcast-scope-streams - 将广播流限定到账户或用户
bcast-refresh-over-replace - 优先使用广播刷新而非细粒度流更新
bcast-avoid-view-logic-in-models - 避免在模型中包含广播逻辑
bcast-signed-stream-names - 使用签名流名称以确保安全
bcast-reconnect-handling - 处理 WebSocket 断开和重新连接

5. 形态变换与页面刷新（高）

morph-enable-page-refresh - 启用形态变换以进行页面刷新
morph-permanent-elements - 将有状态元素标记为永久
morph-scroll-preservation - 在形态变换期间保留滚动位置
morph-stimulus-reconnect - 处理形态变换后 Stimulus 控制器的重新连接
morph-frame-refresh - 在帧上使用 refresh=‘morph’ 以添加内容
morph-vs-streams - 选择形态变换而非复杂流编排

6. 性能优化（中高）

perf-optimistic-ui - 在服务器确认前实施乐观 UI 更新
perf-batch-streams - 将多个流更新批处理为单个响应
perf-frame-caching - 使用片段缓存缓存 Turbo Frame 响应
perf-prefetch-strategic - 在昂贵端点上禁用预取
perf-memory-leak-prevention - 清理订阅和事件监听器

7. Stimulus 模式（中高）

stim-outlets-communication - 使用出口进行跨控制器通信
stim-values-reactive-state - 使用 Values API 实现响应式控制器状态
stim-action-descriptors - 使用声明性操作描述符而非 addEventListener
stim-small-reusable-controllers - 保持 Stimulus 控制器小而可重用

8. 架构决策（中）

arch-progressive-enhancement - 遵循渐进增强层次结构
arch-frame-vs-stream-decision - 使用帧进行限定导航，使用流进行多目标更新
arch-importmap-management - 使用导入映射固定 JavaScript 依赖
arch-avoid-client-state - 在服务器而非客户端保持状态
arch-stimulus-boundaries - 仅使用 Stimulus 处理客户端行为

9. 测试 Hotwire（中）

test-system-test-async - 在系统测试中等待 Turbo 更新
test-stream-assertions - 在集成测试中使用 Turbo Stream 测试助手
test-broadcast-assertions - 使用 Turbo 测试助手断言广播
test-frame-navigation - 使用限定断言测试帧导航
test-websocket-timing - 在系统测试中处理 WebSocket 连接时序

如何使用

阅读个别参考文件以获取详细解释和代码示例：

部分定义 - 类别结构和影响级别
规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则的模板
metadata.json	版本和参考信息