rails-frontend-hotwire

Rails Frontend Hotwire

Build modern Rails frontends with Hotwire using progressive enhancement.

Files: SKILL.md · EXAMPLES.md · references/workflow.md

HARD-GATE

ALWAYS start with HTML-only, enhance with Hotwire progressively
NEVER use Turbo Frames for full page navigation
ALWAYS test without JavaScript first

Progressive Enhancement Workflow

1. Build plain HTML — implement the feature with standard Rails forms and links, no Hotwire.
2. Identify update regions — decide which parts of the page need partial updates and wrap them in turbo_frame_tag. Validate: load the page and confirm the <turbo-frame> element appears in the DOM with the correct id.
3. Add Turbo Frames / Streams — scope frame navigation or broadcast server-side changes via ActionCable. Validate: open browser DevTools Network tab and confirm frame requests return text/vnd.turbo-stream.html or a full frame response; for ActionCable, verify the subscription appears in the Action Cable log before proceeding.
4. Layer Stimulus — attach controllers only where JavaScript behaviour is needed beyond what Turbo handles. Validate: confirm application.getControllerForElementAndIdentifier(el, 'name') returns the controller instance in the browser console.
5. Verify degraded mode — disable JavaScript in browser DevTools (or run rails test:system with a headless driver set to no_js) and confirm forms submit, links navigate, and data persists correctly without JS.

See references/workflow.md for the full annotated workflow.

Quick Examples

Turbo Frame

<%= turbo_frame_tag "post_#{@post.id}" do %>
  <h1><%= @post.title %></h1>
  <%= link_to "Edit", edit_post_path(@post) %>
<% end %>

Turbo Stream

<%= turbo_stream.append "posts", partial: "post", locals: { post: @post } %>

Stimulus Controller

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["name"]
  greet() { alert(`Hello ${this.nameTarget.value}!`) }
}

Register the controller in app/javascript/controllers/index.js:

import GreetController from "./greet_controller"
application.register("greet", GreetController)

Examples

See EXAMPLES.md for complete examples including:

• Turbo Frame lazy loading
• Turbo Stream broadcasting with ActionCable
• Stimulus controllers with values and classes API
• Progressive enhancement patterns

Advanced Patterns

• ActionCable broadcasting — Server-push streams with broadcasts_to. See EXAMPLES.md.
• Turbo Stream morphing — DOM diffing (Turbo 8+). See EXAMPLES.md.
• Nested frames — Scoped frame navigation. See EXAMPLES.md.
• Stimulus values & classes API — Configurable controllers. See EXAMPLES.md.