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-

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