Agent skill

hotwire-turbo-stimulus

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/hotwire-turbo-stimulus

SKILL.md

Hotwire/Turbo/Stimulus: Modern Rails Frontend

Overview

Hotwire (HTML Over The Wire) is Rails' answer to frontend complexity. Instead of shipping JSON to a heavy JavaScript framework, Hotwire delivers HTML directly from the server.

Hotwire consists of:

  • Turbo Drive: Fast navigation without full page reloads
  • Turbo Frames: Update specific page sections
  • Turbo Streams: Real-time HTML updates via WebSockets or HTTP
  • Stimulus: Lightweight JavaScript controllers for sprinkles of interactivity

Together, they provide rich, reactive UIs with minimal JavaScript and no build step.

Philosophy

Hotwire reflects Rails 8's core principles:

  • NO BUILD: No webpack, no complex toolchains
  • Server-rendered: HTML comes from Rails, not JavaScript
  • Progressive enhancement: Start with HTML, add JavaScript as needed
  • Minimal JavaScript: Write only what browsers can't do
  • Integrated: Works seamlessly with Rails conventions

Most applications need less JavaScript than you think. Hotwire proves it.

Turbo Drive

What It Does

Turbo Drive intercepts link clicks and form submissions, replacing full page loads with AJAX requests that update the page content.

Without Turbo Drive:

Click link → Browser requests page → Full page reload → JavaScript re-initializes

With Turbo Drive:

Click link → AJAX request → Replace <body> → Fast transition

Benefits:

  • Instant navigation
  • Preserved scroll position
  • CSS/JS stay loaded
  • Smooth transitions

How It Works

Automatically enabled when you include Turbo:

javascript
// app/javascript/application.js
import "@hotwired/turbo-rails"

Now all links and forms use Turbo Drive automatically:

erb
<%= link_to "Products", products_path %>
<!-- Navigates via Turbo Drive -->

<%= form_with model: @product do |f| %>
  <!-- Submits via Turbo Drive -->
<% end %>

Disabling Turbo Drive

For specific links/forms:

erb
<%= link_to "External", "https://example.com", data: { turbo: false } %>

<%= form_with model: @product, data: { turbo: false } do |f| %>
  <!-- Regular form submission -->
<% end %>

Turbo Drive Progress Bar

Built-in progress indicator for navigation:

css
/* Customize progress bar */
.turbo-progress-bar {
  height: 5px;
  background-color: #0076ff;
}

Turbo Frames

What They Do

Turbo Frames let you update specific page sections without affecting the rest of the page.

Traditional approach:

Update product → Full page reload → Entire page re-renders

With Turbo Frames:

Update product → Only product frame updates → Rest of page untouched

Basic Usage

erb
<!-- app/views/products/index.html.erb -->
<h1>Products</h1>

<%= turbo_frame_tag "new_product" do %>
  <%= link_to "New Product", new_product_path %>
<% end %>

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

<!-- app/views/products/new.html.erb -->
<%= turbo_frame_tag "new_product" do %>
  <h2>New Product</h2>
  <%= form_with model: @product do |f| %>
    <%= f.text_field :name %>
    <%= f.submit %>
  <% end %>
<% end %>

When clicking "New Product", only the new_product frame updates—the rest of the page stays.

dom_id Helper

Rails provides dom_id for consistent frame IDs:

erb
<%= turbo_frame_tag dom_id(@product) do %>
  <%= render @product %>
<% end %>
<!-- Generates: <turbo-frame id="product_123">...</turbo-frame> -->

Frame Navigation

erb
<!-- Clicking links inside frame navigates the frame -->
<%= turbo_frame_tag "products" do %>
  <% @products.each do |product| %>
    <%= link_to product.name, product_path(product) %>
    <!-- Navigates the frame, not the page -->
  <% end %>
<% end %>

Breaking Out of Frames

Navigate the full page from within a frame:

erb
<%= link_to "View All", products_path, data: { turbo_frame: "_top" } %>
<!-- data-turbo-frame="_top" navigates the whole page -->

Lazy Loading Frames

Load content on demand:

erb
<%= turbo_frame_tag "lazy_content", src: lazy_products_path do %>
  Loading...
<% end %>
<!-- Automatically loads when frame appears in viewport -->

See references/turbo-frames.md for advanced patterns.

Turbo Streams

What They Do

Turbo Streams deliver targeted HTML updates after form submissions or via WebSockets.

Seven Stream Actions:

  • append: Add to bottom of target
  • prepend: Add to top of target
  • replace: Replace entire target
  • update: Replace target's content (keeps the target element)
  • remove: Delete target
  • before: Insert before target
  • after: Insert after target

After Form Submission

ruby
# app/controllers/products_controller.rb
def create
  @product = Product.new(product_params)

  respond_to do |format|
    if @product.save
      format.turbo_stream { render turbo_stream: turbo_stream.prepend("products", @product) }
      format.html { redirect_to @product }
    else
      format.turbo_stream { render turbo_stream: turbo_stream.replace(dom_id(@product), partial: "form", locals: { product: @product }) }
      format.html { render :new, status: :unprocessable_entity }
    end
  end
end
erb
<!-- app/views/products/index.html.erb -->
<div id="products">
  <%= render @products %>
</div>

<%= turbo_frame_tag "new_product" do %>
  <%= render "form", product: @product %>
<% end %>

When form submits, new product prepends to #products list without page reload.

Broadcast Updates (Real-Time)

Stream changes to all connected users:

ruby
# app/models/product.rb
class Product < ApplicationRecord
  after_create_commit -> { broadcast_prepend_to "products", target: "products" }
  after_update_commit -> { broadcast_replace_to "products" }
  after_destroy_commit -> { broadcast_remove_to "products" }
end
erb
<!-- app/views/products/index.html.erb -->
<%= turbo_stream_from "products" %>

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

Now when any user creates/updates/deletes a product, all connected users see the change instantly.

Multiple Stream Actions

ruby
# app/views/products/create.turbo_stream.erb
<%= turbo_stream.prepend "products", @product %>
<%= turbo_stream.update "counter", Product.count %>
<%= turbo_stream.replace "flash", partial: "shared/flash" %>

See references/turbo-streams.md for broadcasting patterns.

Stimulus

What It Does

Stimulus is a modest JavaScript framework for adding behavior to HTML.

Philosophy:

  • HTML is the source of truth
  • Controllers connect to HTML via data attributes
  • Small, focused controllers
  • Progressive enhancement

Basic Structure

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

export default class extends Controller {
  static targets = ["menu"]

  toggle() {
    this.menuTarget.classList.toggle("hidden")
  }
}
erb
<!-- app/views/shared/_header.html.erb -->
<div data-controller="dropdown">
  <button data-action="click->dropdown#toggle">Menu</button>

  <nav data-dropdown-target="menu" class="hidden">
    <a href="/products">Products</a>
    <a href="/about">About</a>
  </nav>
</div>

Data Attributes

Stimulus uses three data attributes:

  1. data-controller: Connects element to Stimulus controller
  2. data-{controller}-target: Marks element as a target
  3. data-action: Connects event to controller method

Targets

Reference elements in controllers:

javascript
export default class extends Controller {
  static targets = ["input", "output", "button"]

  connect() {
    console.log(this.inputTarget)  // First matching element
    console.log(this.inputTargets) // All matching elements
    console.log(this.hasInputTarget) // Boolean check
  }
}
erb
<div data-controller="example">
  <input data-example-target="input">
  <input data-example-target="input">
  <div data-example-target="output"></div>
  <button data-example-target="button">Click</button>
</div>

Actions

Connect events to methods:

erb
<!-- Default event (click for buttons/links, input for form fields) -->
<button data-action="dropdown#toggle">Toggle</button>

<!-- Explicit event -->
<input data-action="keyup->search#query">

<!-- Multiple actions -->
<form data-action="submit->form#submit ajax:success->form#success">

<!-- Action options -->
<button data-action="click->menu#open:prevent">
  <!-- :prevent calls preventDefault() -->
</button>

Values

Pass data to controllers:

javascript
export default class extends Controller {
  static values = {
    url: String,
    count: Number,
    active: Boolean
  }

  connect() {
    console.log(this.urlValue)
    console.log(this.countValue)
    console.log(this.activeValue)
  }

  urlValueChanged(value, previousValue) {
    // Called when value changes
  }
}
erb
<div data-controller="example"
     data-example-url-value="<%= products_path %>"
     data-example-count-value="5"
     data-example-active-value="true">
</div>

See references/stimulus-controllers.md for controller patterns.

Integration Patterns

Turbo Frames + Stimulus

erb
<div data-controller="auto-refresh" data-auto-refresh-interval-value="5000">
  <%= turbo_frame_tag "stats", src: stats_path do %>
    Loading...
  <% end %>
</div>
javascript
// auto_refresh_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static values = { interval: Number }
  static targets = ["frame"]

  connect() {
    this.startRefreshing()
  }

  disconnect() {
    this.stopRefreshing()
  }

  startRefreshing() {
    this.refreshTimer = setInterval(() => {
      this.element.querySelector('turbo-frame').reload()
    }, this.intervalValue)
  }

  stopRefreshing() {
    if (this.refreshTimer) {
      clearInterval(this.refreshTimer)
    }
  }
}

Inline Editing

erb
<%= turbo_frame_tag dom_id(product) do %>
  <div data-controller="inline-edit">
    <span data-inline-edit-target="display">
      <%= product.name %>
    </span>
    <button data-action="inline-edit#edit">Edit</button>
  </div>
<% end %>

Common Patterns

Modal with Turbo Frame

erb
<%= turbo_frame_tag "modal" %>

<%= link_to "New Product", new_product_path, data: { turbo_frame: "modal" } %>

Form renders inside modal frame.

Infinite Scroll

erb
<div data-controller="infinite-scroll" data-action="scroll->infinite-scroll#loadMore">
  <%= turbo_frame_tag "products", src: products_path(page: 1) %>
</div>

Live Search

erb
<%= form_with url: search_products_path, method: :get, data: { turbo_frame: "results", turbo_action: "advance" } do |f| %>
  <%= f.search_field :q, data: { action: "input->debounce#search" } %>
<% end %>

<%= turbo_frame_tag "results" do %>
  <!-- Search results render here -->
<% end %>

Further Reading

For deeper exploration:

  • references/turbo-frames.md: Complete Turbo Frames guide with patterns
  • references/turbo-streams.md: Broadcasting and real-time updates
  • references/stimulus-controllers.md: Building Stimulus controllers

For code examples (in examples/):

  • autosave_controller.js: Auto-save form data
  • character_counter_controller.js: Live character counting
  • clipboard_controller.js: Copy to clipboard functionality
  • confirm_controller.js: Confirmation dialogs
  • dropdown_controller.js: Interactive dropdown menus
  • form_controller.js: Form handling and validation
  • infinite_scroll_controller.js: Infinite scroll pagination
  • modal_controller.js: Modal dialogs with Stimulus
  • nested_form_controller.js: Dynamic nested form fields
  • remote_form_controller.js: AJAX form submissions
  • search_controller.js: Real-time search filtering
  • slideshow_controller.js: Image carousel/slideshow
  • tabs_controller.js: Tab navigation
  • toggle_controller.js: Toggle visibility patterns

Summary

Hotwire provides:

  • Turbo Drive: Fast navigation without full reloads
  • Turbo Frames: Scoped page updates
  • Turbo Streams: Real-time HTML over WebSockets
  • Stimulus: Lightweight JavaScript controllers
  • NO BUILD: No webpack, no complex tooling
  • Server-rendered: HTML from Rails, not JSON APIs

Master Hotwire and build rich, interactive applications with minimal JavaScript.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results