rails-hotwire

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

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