playbooks

home / skills / thebushidocollective / han / rails-hotwire

rails-hotwire skill

/plugins/frameworks/rails/skills/rails-hotwire

This skill helps you build modern reactive Rails apps using Turbo and Stimulus, delivering HTML over the wire without heavy JavaScript frameworks.

npx playbooks add skill thebushidocollective/han --skill rails-hotwire

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
16.4 KB
---
name: rails-hotwire
user-invocable: false
description: Use when hotwire (Turbo and Stimulus) for building modern reactive Rails applications without complex JavaScript frameworks.
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
  - Bash
---

# Rails Hotwire

Master Hotwire for building modern, reactive Rails applications using Turbo
and Stimulus without requiring heavy JavaScript frameworks.

## Overview

Hotwire (HTML Over The Wire) is a modern approach to building web applications
that sends HTML instead of JSON over the wire. It consists of Turbo (for
delivering server-rendered HTML) and Stimulus (for JavaScript sprinkles).

## Installation and Setup

### Installing Hotwire

```bash
# Add to Gemfile
bundle add turbo-rails stimulus-rails

# Install Turbo
rails turbo:install

# Install Stimulus
rails stimulus:install

# Install Redis for ActionCable (Turbo Streams)
bundle add redis

# Configure ActionCable
rails generate channel turbo_stream
```

### Configuration

```ruby
# config/cable.yml
development:
  adapter: redis
  url: redis://localhost:6379/1

production:
  adapter: redis
  url: <%= ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" } %>
  channel_prefix: myapp_production

# config/routes.rb
Rails.application.routes.draw do
  mount ActionCable.server => '/cable'
end
```

## Core Patterns

### 1. Turbo Drive (Page Acceleration)

```ruby
# Turbo Drive is automatic, but you can customize behavior

# app/views/layouts/application.html.erb
<!DOCTYPE html>
<html>
  <head>
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>
    <%= turbo_refreshes_with method: :morph, scroll: :preserve %>
  </head>
  <body>
    <%= yield %>
  </body>
</html>

# Disable Turbo for specific links
<%= link_to "Legacy Page", legacy_path, data: { turbo: false } %>

# Disable Turbo for forms
<%= form_with url: upload_path, data: { turbo: false } do |f| %>
  <%= f.file_field :document %>
<% end %>

# Custom progress bar
<style>
  .turbo-progress-bar {
    background: linear-gradient(to right, #4ade80, #3b82f6);
  }
</style>
```

### 2. Turbo Frames (Lazy Loading & Decomposition)

```ruby
# app/views/posts/index.html.erb
<div id="posts">
  <% @posts.each do |post| %>
    <%= turbo_frame_tag dom_id(post) do %>
      <%= render post %>
    <% end %>
  <% end %>
</div>

# app/views/posts/_post.html.erb
<article>
  <h2><%= post.title %></h2>
  <p><%= post.body %></p>

  <%= link_to "Edit", edit_post_path(post) %>
  <%= link_to "Delete", post_path(post),
              data: { turbo_method: :delete,
                      turbo_confirm: "Are you sure?" } %>
</article>

# app/views/posts/edit.html.erb
<%= turbo_frame_tag dom_id(@post) do %>
  <%= form_with model: @post do |f| %>
    <%= f.text_field :title %>
    <%= f.text_area :body %>
    <%= f.submit %>
  <% end %>
<% end %>

# Lazy loading frames
<%= turbo_frame_tag "analytics", src: analytics_path, loading: :lazy do %>
  <p>Loading analytics...</p>
<% end %>

# Target different frames
<%= link_to "Show Post", post_path(post),
            data: { turbo_frame: "modal" } %>

# Break out of frame
<%= link_to "New Page", new_post_path,
            data: { turbo_frame: "_top" } %>
```

### 3. Turbo Streams (Real-time Updates)

```ruby
# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  def create
    @post = Post.new(post_params)

    respond_to do |format|
      if @post.save
        format.turbo_stream
        format.html { redirect_to @post }
      else
        format.html { render :new, status: :unprocessable_entity }
      end
    end
  end

  def destroy
    @post = Post.find(params[:id])
    @post.destroy

    respond_to do |format|
      format.turbo_stream { render turbo_stream: turbo_stream.remove(@post) }
      format.html { redirect_to posts_path }
    end
  end
end

# app/views/posts/create.turbo_stream.erb
<%= turbo_stream.prepend "posts", partial: "posts/post",
                         locals: { post: @post } %>
<%= turbo_stream.update "new_post", "" %>
<%= turbo_stream.replace "flash",
    partial: "shared/flash",
    locals: { message: "Post created!" } %>

# Multiple Turbo Stream actions
<%= turbo_stream.append "notifications" do %>
  <div class="notification">New post created!</div>
<% end %>

<%= turbo_stream.update "post_count",
    Post.count %>

<%= turbo_stream.remove "loading_spinner" %>

<%= turbo_stream.replace dom_id(@post),
    partial: "posts/post",
    locals: { post: @post } %>
```

### 4. Broadcasting Updates

```ruby
# app/models/post.rb
class Post < ApplicationRecord
  broadcasts_to ->(post) { [post.user, "posts"] }, inserts_by: :prepend

  # Or more explicit
  after_create_commit -> {
    broadcast_prepend_to "posts",
      partial: "posts/post",
      locals: { post: self },
      target: "posts"
  }

  after_update_commit -> {
    broadcast_replace_to "posts",
      partial: "posts/post",
      locals: { post: self },
      target: dom_id(self)
  }

  after_destroy_commit -> {
    broadcast_remove_to "posts", target: dom_id(self)
  }
end

# app/views/posts/index.html.erb
<%= turbo_stream_from "posts" %>

<div id="posts">
  <%= render @posts %>
</div>

# Broadcast to specific users
class Comment < ApplicationRecord
  belongs_to :post

  after_create_commit -> {
    broadcast_prepend_to [post.user, :comments],
      partial: "comments/comment",
      locals: { comment: self },
      target: "comments"
  }
end

# app/views/posts/show.html.erb
<%= turbo_stream_from current_user, :comments %>
```

### 5. Stimulus Controllers

```javascript
// app/javascript/controllers/clipboard_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["source", "button"]
  static values = {
    successMessage: String,
    errorMessage: String
  }

  copy(event) {
    event.preventDefault()

    navigator.clipboard.writeText(this.sourceTarget.value).then(
      () => this.showSuccess(),
      () => this.showError()
    )
  }

  showSuccess() {
    this.buttonTarget.textContent = this.successMessageValue || "Copied!"
    setTimeout(() => {
      this.buttonTarget.textContent = "Copy"
    }, 2000)
  }

  showError() {
    this.buttonTarget.textContent = this.errorMessageValue || "Failed!"
  }
}
```

```erb
<!-- app/views/posts/show.html.erb -->
<div data-controller="clipboard"
     data-clipboard-success-message-value="Copied to clipboard!">
  <input type="text"
         value="<%= @post.share_url %>"
         data-clipboard-target="source"
         readonly>
  <button data-clipboard-target="button"
          data-action="click->clipboard#copy">
    Copy
  </button>
</div>
```

### 6. Form Validation with Stimulus

```javascript
// app/javascript/controllers/form_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["email", "password", "submit"]
  static classes = ["error"]

  connect() {
    this.validateForm()
  }

  validateField(event) {
    const field = event.target
    const isValid = field.checkValidity()

    if (isValid) {
      field.classList.remove(this.errorClass)
    } else {
      field.classList.add(this.errorClass)
    }

    this.validateForm()
  }

  validateForm() {
    const isValid = this.element.checkValidity()
    this.submitTarget.disabled = !isValid
  }

  async submit(event) {
    event.preventDefault()

    if (!this.element.checkValidity()) {
      return
    }

    const formData = new FormData(this.element)
    const response = await fetch(this.element.action, {
      method: this.element.method,
      body: formData,
      headers: {
        "Accept": "text/vnd.turbo-stream.html"
      }
    })

    if (response.ok) {
      const html = await response.text()
      Turbo.renderStreamMessage(html)
    }
  }
}
```

```erb
<%= form_with model: @user,
    data: { controller: "form",
            form_error_class: "border-red-500" } do |f| %>

  <%= f.email_field :email,
      required: true,
      data: { form_target: "email",
              action: "blur->form#validateField" } %>

  <%= f.password_field :password,
      required: true,
      minlength: 8,
      data: { form_target: "password",
              action: "blur->form#validateField" } %>

  <%= f.submit "Sign Up",
      data: { form_target: "submit",
              action: "click->form#submit" } %>
<% end %>
```

### 7. Infinite Scroll

```javascript
// app/javascript/controllers/infinite_scroll_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["entries", "pagination"]
  static values = {
    url: String,
    page: Number
  }

  initialize() {
    this.scroll = this.scroll.bind(this)
  }

  connect() {
    this.createObserver()
  }

  disconnect() {
    this.observer.disconnect()
  }

  createObserver() {
    this.observer = new IntersectionObserver(
      entries => this.handleIntersect(entries),
      { threshold: 1.0 }
    )
    this.observer.observe(this.paginationTarget)
  }

  handleIntersect(entries) {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        this.loadMore()
      }
    })
  }

  async loadMore() {
    const url = this.paginationTarget.querySelector("a[rel='next']")?.href

    if (!url) return

    this.pageValue++

    const response = await fetch(url, {
      headers: {
        Accept: "text/vnd.turbo-stream.html"
      }
    })

    if (response.ok) {
      const html = await response.text()
      Turbo.renderStreamMessage(html)
    }
  }
}
```

```erb
<!-- app/views/posts/index.html.erb -->
<div data-controller="infinite-scroll">
  <div id="posts" data-infinite-scroll-target="entries">
    <%= render @posts %>
  </div>

  <div data-infinite-scroll-target="pagination">
    <%= paginate @posts %>
  </div>
</div>

<!-- app/views/posts/index.turbo_stream.erb -->
<%= turbo_stream.append "posts" do %>
  <%= render @posts %>
<% end %>

<%= turbo_stream.replace "pagination" do %>
  <%= paginate @posts %>
<% end %>
```

### 8. Modal Dialogs

```javascript
// app/javascript/controllers/modal_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["container", "backdrop"]

  connect() {
    document.body.classList.add("overflow-hidden")
  }

  disconnect() {
    document.body.classList.remove("overflow-hidden")
  }

  close(event) {
    if (event.target === this.backdropTarget ||
        event.currentTarget.dataset.closeModal === "true") {
      this.element.remove()
    }
  }

  closeWithKeyboard(event) {
    if (event.key === "Escape") {
      this.element.remove()
    }
  }
}
```

```erb
<!-- app/views/posts/_modal.html.erb -->
<div data-controller="modal"
     data-action="keyup@window->modal#closeWithKeyboard"
     class="fixed inset-0 z-50">

  <div data-modal-target="backdrop"
       data-action="click->modal#close"
       class="fixed inset-0 bg-black bg-opacity-50"></div>

  <div data-modal-target="container"
       class="fixed inset-0 flex items-center justify-center">
    <div class="bg-white rounded-lg p-6 max-w-lg">
      <%= turbo_frame_tag "modal_content" do %>
        <%= yield %>
      <% end %>

      <button data-close-modal="true"
              data-action="click->modal#close">
        Close
      </button>
    </div>
  </div>
</div>

<!-- Trigger modal -->
<%= link_to "Edit Post",
    edit_post_path(@post),
    data: { turbo_frame: "modal" } %>
```

### 9. Autosave with Stimulus

```javascript
// app/javascript/controllers/autosave_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["status"]
  static values = {
    delay: { type: Number, default: 1000 },
    url: String
  }

  connect() {
    this.timeout = null
    this.saving = false
  }

  save() {
    clearTimeout(this.timeout)

    this.timeout = setTimeout(() => {
      this.persist()
    }, this.delayValue)
  }

  async persist() {
    if (this.saving) return

    this.saving = true
    this.showStatus("Saving...")

    const formData = new FormData(this.element)

    try {
      const response = await fetch(this.urlValue, {
        method: "PATCH",
        body: formData,
        headers: {
          "X-CSRF-Token": document.querySelector("[name='csrf-token']").content,
          "Accept": "application/json"
        }
      })

      if (response.ok) {
        this.showStatus("Saved", "success")
      } else {
        this.showStatus("Error saving", "error")
      }
    } catch (error) {
      this.showStatus("Error saving", "error")
    } finally {
      this.saving = false
    }
  }

  showStatus(message, type = "info") {
    this.statusTarget.textContent = message
    this.statusTarget.className = `status-${type}`

    setTimeout(() => {
      this.statusTarget.textContent = ""
    }, 2000)
  }
}
```

```erb
<%= form_with model: @post,
    data: { controller: "autosave",
            autosave_url_value: post_path(@post),
            action: "input->autosave#save" } do |f| %>

  <div data-autosave-target="status"></div>

  <%= f.text_field :title %>
  <%= f.text_area :body %>
<% end %>
```

### 10. Search with Debouncing

```javascript
// app/javascript/controllers/search_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["input", "results"]
  static values = {
    url: String,
    delay: { type: Number, default: 300 }
  }

  connect() {
    this.timeout = null
  }

  search() {
    clearTimeout(this.timeout)

    this.timeout = setTimeout(() => {
      this.performSearch()
    }, this.delayValue)
  }

  async performSearch() {
    const query = this.inputTarget.value

    if (query.length < 2) {
      this.resultsTarget.innerHTML = ""
      return
    }

    const url = new URL(this.urlValue)
    url.searchParams.set("q", query)

    const response = await fetch(url, {
      headers: {
        Accept: "text/vnd.turbo-stream.html"
      }
    })

    if (response.ok) {
      const html = await response.text()
      Turbo.renderStreamMessage(html)
    }
  }

  clear() {
    this.inputTarget.value = ""
    this.resultsTarget.innerHTML = ""
  }
}
```

```erb
<div data-controller="search"
     data-search-url-value="<%= search_posts_path %>">

  <input type="text"
         data-search-target="input"
         data-action="input->search#search"
         placeholder="Search posts...">

  <button data-action="click->search#clear">Clear</button>

  <div id="search-results" data-search-target="results"></div>
</div>
```

## Best Practices

1. **Use Turbo Frames for isolation** - Scope updates to specific parts
2. **Broadcast model changes** - Keep all clients synchronized
3. **Progressive enhancement** - Ensure functionality without JavaScript
4. **Lazy load frames** - Improve initial page load performance
5. **Use Stimulus for sprinkles** - Keep JavaScript minimal and focused
6. **Leverage Turbo Streams** - Update multiple parts of the page
7. **Handle errors gracefully** - Provide fallbacks for network issues
8. **Cache appropriately** - Use HTTP caching with Turbo
9. **Test real-time features** - Verify broadcasts work correctly
10. **Optimize database queries** - Prevent N+1 with includes/preload

## Common Pitfalls

1. **Over-using Turbo Frames** - Not everything needs to be a frame
2. **Missing CSRF tokens** - Forgetting tokens in AJAX requests
3. **Race conditions** - Not handling concurrent broadcasts
4. **Memory leaks** - Not disconnecting ActionCable subscriptions
5. **Flash message issues** - Flash persisting across Turbo requests
6. **Breaking browser history** - Improper Turbo navigation
7. **SEO concerns** - Not considering search engine crawlers
8. **Form state loss** - Losing unsaved data on navigation
9. **Accessibility issues** - Not managing focus and ARIA attributes
10. **Over-engineering** - Using Hotwire when simple HTML suffices

## When to Use

- Building modern Rails applications
- Creating real-time collaborative features
- Implementing live updates without polling
- Building single-page-like experiences
- Reducing JavaScript complexity
- Progressive enhancement scenarios
- Mobile-friendly responsive interfaces
- Admin dashboards with live data
- Chat and messaging applications
- Live notifications and feeds

## Resources

- [Hotwire Documentation](https://hotwired.dev/)
- [Turbo Handbook](https://turbo.hotwired.dev/handbook/introduction)
- [Stimulus Handbook](https://stimulus.hotwired.dev/handbook/introduction)
- [Turbo Rails Gem](https://github.com/hotwired/turbo-rails)
- [Stimulus Components](https://www.stimulus-components.com/)
- [GoRails Hotwire Tutorials](https://gorails.com/series/hotwire-rails)

Overview

This skill teaches Hotwire (Turbo and Stimulus) patterns for building reactive Rails applications without heavy JavaScript frameworks. It focuses on server-rendered HTML over the wire, real-time updates, and small Stimulus controllers to add interactivity. The goal is faster development, simpler front-end code, and resilient UX that degrades gracefully.

How this skill works

The skill explains how Turbo Drive, Turbo Frames, and Turbo Streams deliver HTML fragments and stream updates from the Rails server. It shows how to broadcast model changes via ActionCable/Redis and how to write Stimulus controllers for client-side behaviors like clipboard actions, infinite scroll, modals, autosave, and debounced search. Examples include controller actions with turbo_stream responses and broadcast hooks in models.

When to use it

  • When you want reactive UI without a SPA framework (React/Vue).
  • When server-rendered HTML is preferred for SEO and simplicity.
  • When you need real-time updates via Turbo Streams and ActionCable.
  • When you want small, focused JavaScript using Stimulus.
  • When you need progressive enhancement and graceful degradation.

Best practices

  • Keep Stimulus controllers focused and testable: one responsibility per controller.
  • Use Turbo Frames to decompose pages and lazy-load expensive sections.
  • Return turbo_stream responses for create/update/destroy to update the DOM atomically.
  • Broadcast model changes with broadcasts_to or after_commit callbacks for real-time UX.
  • Prefer Accept: text/vnd.turbo-stream.html for fetches that should render stream actions.

Example use cases

  • A blog where new posts prepend in real time to all viewers with Turbo Streams.
  • A paginated index with infinite scroll handled by a Stimulus controller and turbo_stream append.
  • Inline editing in a modal using turbo_frame_tag and a Stimulus modal controller.
  • Autosave draft content with a Stimulus autosave controller that PATCHes and shows status.
  • Debounced search that fetches results as turbo_stream and updates a results frame.

FAQ

Do I need Redis or ActionCable?

Use Redis and ActionCable for Turbo Streams broadcasting in production. Local development can use async adapters but Redis is recommended for reliability and scaling.

When should I disable Turbo for links or forms?

Disable Turbo for file uploads, third-party redirects, or when native full-page navigation is required. Use data-turbo="false" on links or forms.