rails-hotwire

Original：🇺🇸 English

Translated

Ruby on Rails Hotwire best practices for building interactive applications with Turbo Drive, Turbo Frames, Turbo Streams, Turbo 8 morphing, and Stimulus controllers. This skill should be used when writing, reviewing, or refactoring Hotwire-powered Rails code to ensure optimal patterns for navigation, partial page updates, real-time broadcasting, morphing, Stimulus controller design, error handling, and progressive enhancement. Triggers on tasks involving Turbo Frames, Turbo Streams, Turbo Drive, broadcasts, morphing, Stimulus controllers, ActionCable, turbo_stream_from, turbo_frame_tag, data-controller, data-action, or Hotwire performance. Complementary to rails-dev, rails-testing, rails-design-system, ruby-optimise, and ruby-refactor skills.

2installs

Sourcepproenca/dot-skills

Added on2026-02-16

NPX Install

npx skill4agent add pproenca/dot-skills rails-hotwire

SKILL.md Content

View Translation Comparison →

Community Rails Hotwire Best Practices

Comprehensive guide for building interactive Rails applications with Hotwire (Turbo + Stimulus), maintained by Community. Contains 53 rules across 9 categories, prioritized by impact to guide automated refactoring and code generation. Follows the DHH "One Person Framework" philosophy: the server renders HTML, Turbo makes it feel like an SPA, Stimulus adds the sprinkle of JS where needed.

When to Apply

Reference these guidelines when:

Configuring Turbo Drive navigation, prefetching, and caching behavior
Adding Turbo Frames for partial page updates and lazy loading
Delivering Turbo Streams for surgical DOM mutations
Broadcasting real-time updates over ActionCable
Enabling Turbo 8 morphing for page refreshes
Writing Stimulus controllers for client-side behavior
Handling errors in Turbo navigation, frames, and WebSocket connections
Choosing between Drive, Frames, Streams, Morphing, and Stimulus
Testing Hotwire interactions in system and integration tests

Rule Categories by Priority


drive-
frame-
stream-
bcast-
morph-
perf-
stim-
arch-
test-

Priority	Category	Impact	Prefix
1	Navigation & Drive	CRITICAL	`drive-`
2	Turbo Frames	CRITICAL	`frame-`
3	Turbo Streams	HIGH	`stream-`
4	Broadcasting & Real-Time	HIGH	`bcast-`
5	Morphing & Page Refresh	HIGH	`morph-`
6	Performance Optimization	MEDIUM-HIGH	`perf-`
7	Stimulus Patterns	MEDIUM-HIGH	`stim-`
8	Architecture Decisions	MEDIUM	`arch-`
9	Testing Hotwire	MEDIUM	`test-`

Quick Reference

1. Navigation & Drive (CRITICAL)

```
drive-prefetch-links
```
- Enable link prefetching for instant navigation
```
drive-form-submissions
```
- Use Turbo Drive for form submissions
```
drive-visit-actions
```
- Control history with visit actions
```
drive-cache-control
```
- Configure Turbo cache for preview pages
```
drive-selective-disable
```
- Disable Turbo Drive on incompatible pages
```
drive-progress-bar
```
- Customize the Turbo progress bar
```
drive-confirm-dialog
```
- Use data-turbo-confirm for destructive actions
```
drive-error-recovery
```
- Handle Turbo navigation and fetch errors gracefully

2. Turbo Frames (CRITICAL)

```
frame-lazy-loading
```
- Defer frame loading until viewport entry
```
frame-scope-navigation
```
- Scope navigation within frames
```
frame-src-navigation
```
- Use src for dynamic frame content
```
frame-break-out
```
- Handle frame breakout for redirects
```
frame-promote-visits
```
- Promote frame navigation to page visits
```
frame-dom-id
```
- Use dom_id for frame identification
```
frame-empty-state
```
- Provide meaningful frame loading states

3. Turbo Streams (HIGH)

```
stream-progressive-enhance
```
- Always provide HTML fallback for streams
```
stream-action-selection
```
- Choose the right stream action for DOM mutations
```
stream-multi-target
```
- Use targets for multi-element updates
```
stream-http-delivery
```
- Deliver streams via HTTP for form responses
```
stream-websocket-source
```
- Connect WebSocket sources in the body
```
stream-custom-actions
```
- Register custom stream actions for complex DOM updates

4. Broadcasting & Real-Time (HIGH)

```
bcast-model-broadcasts
```
- Use broadcasts_refreshes for simple model updates
```
bcast-debounce-n1
```
- Debounce broadcasts to prevent N+1 broadcast storms
```
bcast-scope-streams
```
- Scope broadcast streams to accounts or users
```
bcast-refresh-over-replace
```
- Prefer broadcast refresh over granular stream updates
```
bcast-avoid-view-logic-in-models
```
- Keep broadcasting logic out of models
```
bcast-signed-stream-names
```
- Use signed stream names for security
```
bcast-reconnect-handling
```
- Handle WebSocket disconnection and reconnection

5. Morphing & Page Refresh (HIGH)

```
morph-enable-page-refresh
```
- Enable morphing for page refreshes
```
morph-permanent-elements
```
- Mark stateful elements as permanent
```
morph-scroll-preservation
```
- Preserve scroll position during morphing
```
morph-stimulus-reconnect
```
- Handle Stimulus controller reconnection after morph
```
morph-frame-refresh
```
- Use refresh='morph' on frames for additive content
```
morph-vs-streams
```
- Choose morphing over complex stream orchestration

6. Performance Optimization (MEDIUM-HIGH)

```
perf-optimistic-ui
```
- Implement optimistic UI updates before server confirmation
```
perf-batch-streams
```
- Batch multiple stream updates into single responses
```
perf-frame-caching
```
- Cache Turbo Frame responses with fragment caching
```
perf-prefetch-strategic
```
- Disable prefetch on expensive endpoints
```
perf-memory-leak-prevention
```
- Clean up subscriptions and event listeners

7. Stimulus Patterns (MEDIUM-HIGH)

```
stim-outlets-communication
```
- Use outlets for cross-controller communication
```
stim-values-reactive-state
```
- Use Values API for reactive controller state
```
stim-action-descriptors
```
- Use declarative action descriptors over addEventListener
```
stim-small-reusable-controllers
```
- Keep Stimulus controllers small and reusable

8. Architecture Decisions (MEDIUM)

```
arch-progressive-enhancement
```
- Follow the progressive enhancement hierarchy
```
arch-frame-vs-stream-decision
```
- Use frames for scoped navigation, streams for multi-target updates
```
arch-importmap-management
```
- Pin JavaScript dependencies with import maps
```
arch-avoid-client-state
```
- Keep state on the server, not the client
```
arch-stimulus-boundaries
```
- Use Stimulus only for client-side behavior

9. Testing Hotwire (MEDIUM)

```
test-system-test-async
```
- Wait for Turbo updates in system tests
```
test-stream-assertions
```
- Use Turbo Stream test helpers in integration tests
```
test-broadcast-assertions
```
- Assert broadcasts with Turbo test helpers
```
test-frame-navigation
```
- Test frame navigation with scoped assertions
```
test-websocket-timing
```
- Handle WebSocket connection timing in system tests

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information