Skip to main content
affpapa.org
RU EN
skill CX Codex

rails-hotwire · pproenca — Claude Code skill: Hotwire for Rails

A skill with Hotwire rules for Rails: Turbo Drive, Frames, Streams, Turbo 8 morphing and Stimulus controllers. Useful when writing or refactoring interactive pages.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add pproenca/dot-skills --skill rails-hotwire -a claude-code
Open on GitHub

What rails-hotwire does

The skill packs 53 rules across 9 categories, ordered by priority. Navigation and Turbo Drive come first, then Frames, Streams, ActionCable broadcasting, Turbo 8 morphing, performance, Stimulus, architecture decisions and testing. Each rule lives in its own file under references/ and is addressed by name, like frame-lazy-loading or bcast-debounce-n1.

The philosophy inside is DHH's "One Person Framework": the server renders HTML, Turbo makes it feel like an SPA, Stimulus adds JS where nothing else fits. The skill helps pick between Drive, Frames, Streams, morphing and a controller for a given task. Navigation errors, WebSocket disconnects and reconnects, leaked subscriptions and event listeners each get their own rule.

The author lists it as complementary to rails-dev, rails-testing, rails-design-system, ruby-optimise and ruby-refactor. Installing it on its own buys you little: the rules lean on the same Rails patterns, so without the base Rails skill some advice has nothing to attach to. Install runs through npx skills add with a flag per platform.

What it helps with

  • choose between Turbo Frames and Streams for a partial page update
  • defer frame loading until the element enters the viewport
  • stop broadcast storms caused by N+1 updates on a model
  • turn on page morphing and keep the scroll position
  • debug a Stimulus controller that died after a morph

Example prompts for the agent

  • Rewrite this controller with Turbo Frames and tell me where lazy loading fits
  • Review the ActionCable broadcasts in the Post model against rails-hotwire rules
  • Enable morphing for page refresh and mark the permanent elements

How to install rails-hotwire

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill rails-hotwire -a claude-code

2Manually: put the files in place

~/.claude/skills/rails-hotwire/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/rails-hotwire/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about rails-hotwire

How do I install rails-hotwire in Claude?

Run npx skills add pproenca/dot-skills --skill rails-hotwire -a claude-code. The skill lands at ~/.claude/skills/rails-hotwire/SKILL.md.

What does rails-hotwire do?

It hands the agent a rule set for Hotwire: Turbo Drive navigation, frames, streams, broadcasting, Turbo 8 morphing and Stimulus controllers. Rules are ranked by priority so the agent picks one approach instead of mixing them.

Which skills does it pair with?

The author calls it complementary to rails-dev, rails-testing, rails-design-system, ruby-optimise and ruby-refactor. Without those, the Rails-side rules have nothing to build on.

Source text

SKILL.md · MIT 
---
name: rails-hotwire
description: 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.
---

# 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`](references/drive-prefetch-links.md) - Enable link prefetching for instant navigation
- [`drive-form-submissions`](references/drive-form-submissions.md) - Use Turbo Drive for form submissions
- [`drive-visit-actions`](references/drive-visit-actions.md) - Control history with visit actions
- [`drive-cache-control`](references/drive-cache-control.md) - Configure Turbo cache for preview pages
- [`drive-selective-disable`](references/drive-selective-disable.md) - Disable Turbo Drive on incompatible pages
- [`drive-progress-bar`](references/drive-progress-bar.md) - Customize the Turbo progress bar
- [`drive-confirm-dialog`](references/drive-confirm-dialog.md) - Use data-turbo-confirm for destructive actions
- [`drive-error-recovery`](references/drive-error-recovery.md) - Handle Turbo navigation and fetch errors gracefully

### 2. Turbo Frames (CRITICAL)

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

### 3. Turbo Streams (HIGH)

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

### 4. Broadcasting & Real-Time (HIGH)

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

### 5. Morphing & Page Refresh (HIGH)

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

### 6. Performance Optimization (MEDIUM-HIGH)

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

### 7. Stimulus Patterns (MEDIUM-HIGH)

- [`stim-outlets-communication`](references/stim-outlets-communication.md) - Use outlets for cross-controller communication
- [`stim-values-reactive-state`](references/stim-values-reactive-state.md) - Use Values API for reactive controller state
- [`stim-action-descriptors`](references/stim-action-descriptors.md) - Use declarative action descriptors over addEventListener
- [`stim-small-reusable-controllers`](references/stim-small-reusable-controllers.md) - Keep Stimulus controllers small and reusable

### 8. Architecture Decisions (MEDIUM)

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

### 9. Testing Hotwire (MEDIUM)

- [`test-system-test-async`](references/test-system-test-async.md) - Wait for Turbo updates in system tests
- [`test-stream-assertions`](references/test-stream-assertions.md) - Use Turbo Stream test helpers in integration tests
- [`test-broadcast-assertions`](references/test-broadcast-assertions.md) - Assert broadcasts with Turbo test helpers
- [`test-frame-navigation`](references/test-frame-navigation.md) - Test frame navigation with scoped assertions
- [`test-websocket-timing`](references/test-websocket-timing.md) - Handle WebSocket connection timing in system tests

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

© pproenca · MIT · pproenca/dot-skills

Similar skills

Everything for Frontend and UI →

rails-hotwire by other authors comes first.

rails-hotwire TheBushidoCollective A skill for Hotwire in Rails: Turbo Frames, Turbo Streams, broadcasts and Stimulus controllers. Useful when you want reactive pages without a heavy JS framework. CX Codex +1 348installs ruby-rails Mindrally This skill hands your agent Rails conventions: generators over boilerplate, ActiveRecord patterns, Hotwire, background jobs and tests. Useful on a fresh app or an existing one. CX Codex +1 862installs rails-cursorrules-prompt-file PatrickJS A Cursor rule file that tells the agent how to write Rails 8 code: generators, bin/dev, the Solid stack, Minitest and Hotwire. ★ 41,011repo stars rails-expert https://github.com/Jeffallan Rails 7+ skill for Hotwire, Sidekiq, and Active Record optimization. Guides query tuning, Turbo Frames, and RSpec test suites. CX Codex +1 4,700installs ruby-rails-application aj-geddes Guides building Ruby on Rails applications with Active Record models, RESTful controllers, and JWT authentication. Best for structuring Rails APIs and managing database schemas. CX Codex +1 655installs inertia-rails-controllers inertia-rails Tells the agent how to return data from Rails controllers to Inertia.js: render inertia, prop types, shared data, flash and validation errors. CX Codex +1 491installs inertia-rails-testing inertia-rails A skill that tells your agent how to test Inertia Rails responses with RSpec and Minitest matchers instead of raw JSON checks. CX Codex +1 465installs

From the same set45

jscodeshift A rule set for writing and debugging jscodeshift codemods: AST traversal, code migrations, automated refactoring. CX Codex +1 410installs expo-react-native-coder A skill with 50 rules and code templates for building Expo and React Native apps. Useful for screens, navigation and auth flows. CX Codex +1 409installs react-testing-library A skill with 43 React Testing Library rules. It steers the agent toward tests that check behaviour instead of component internals. CX Codex +1 402installs react-optimise A skill that walks through React app performance: React Compiler, bundle size, rendering, data fetching, Core Web Vitals. Useful when your app feels slow. CX Codex +1 396installs nginx-c-module-design A skill for anyone writing nginx C modules: it helps you decide what to expose as directives, how to name them and where they belong. Most useful while the module's config interface is still being shaped. CX Codex +1 352installs nginx-c-modules A skill that feeds your agent 49 rules for nginx C module work: pool memory, request lifecycle, config merging. Useful when you write or refactor a handler, filter or upstream. CX Codex +1 349installs dockerfile-optimise A skill with 48 rules from official Docker docs: layer caching, multi-stage builds, security. Useful when writing or refactoring Dockerfiles. CX Codex +1 344installs uniwind A skill with 45+ rules for Uniwind, the Tailwind bindings for React Native. Useful when setting up a project, building themes or migrating from NativeWind. CX Codex +1 341installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor