rails-frontend

Rails Frontend

Core conventions for Rails frontend work using the Hotwire stack: Turbo Drive, Turbo Frames, Turbo Streams, and Stimulus controllers.

Sub-files

• VIEWS.md — ERB conventions, layouts, partials, Turbo Frame wrapping
• COMPONENTS.md — Stimulus controllers, presenter pattern, component composition
• ASSETS.md — CSS architecture, design tokens, asset pipeline

---

Stack

• Turbo Drive — replaces full page loads with fetch + DOM swap
• Turbo Frames — scope navigation to a region; swap on response
• Turbo Streams — targeted DOM mutations via <turbo-stream> elements
• Stimulus — lightweight JS controllers bound to DOM elements
• No React/Vue — Hotwire is the default; reach for Stimulus before any SPA framework

---

Turbo Essentials

HTTP Status Codes

Always use these — Turbo depends on them:

Status	Meaning	When to Use
303 See Other	Redirect after success	After any create/update/destroy
422 Unprocessable Entity	Validation failure	Re-render form in frame
Never 200	For redirect-expecting forms	—

def create
  if @card.save
    redirect_to @card, status: :see_other
  else
    render :new, status: :unprocessable_entity
  end
end

Turbo Frames

Scope to the smallest rerenderable unit. Always use dom_id for IDs:

<turbo-frame id="<%= dom_id(card) %>">
  <%= render "cards/card", card: card %>
</turbo-frame>

Lazy loading with placeholder:

<turbo-frame id="activity_feed" src="<%= activity_feed_path %>" loading="lazy">
  <p>Loading...</p>
</turbo-frame>

Style the loading state with the auto-added [busy] attribute:

turbo-frame[busy] { opacity: 0.5; pointer-events: none; }

Turbo Streams

Prefer the 8 built-in actions: append, prepend, replace, update, remove, before, after, refresh.

Broadcast from model callbacks:

class Card < ApplicationRecord
  after_create_commit  -> { broadcast_append_to board, target: "cards" }
  after_update_commit  -> { broadcast_replace_to board }
  after_destroy_commit -> { broadcast_remove_to board }
end