implement-hotwire

Hotwire の実装

プログレッシブエンハンスメントを用いて、Hotwire でモダンな Rails フロントエンドを構築します。

クイックリファレンス

目的	Hotwire の選択肢
リンク/フォーム送信後にページの一部を置き換える	Turbo Frame
サーバー側の変更をブロードキャストする	Turbo Stream
Turbo を超えたクライアント限定の挙動	Stimulus コントローラー
ページ全体のナビゲーション	通常の Rails ナビゲーション（フレームではない）

ハードゲート

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

コアプロセス

1. プレーンな HTML を構築する — Hotwire を使わず、標準的な Rails のフォームとリンクで機能を実装します。
2. 更新リージョンを特定する — 部分更新する領域を turbo_frame_tag で囲みます。検証: <turbo-frame> が正しい id で DOM に現れることを確認します。
3. Turbo Frames / Streams を追加する — フレームナビゲーションをスコープするか、ActionCable 経由でブロードキャストします。検証: DevTools の Network タブでフレームリクエストが text/vnd.turbo-stream.html を返すことを確認します。ActionCable の場合は、Action Cable のログにサブスクリプションが現れることを確認します。
4. Stimulus を重ねる — Turbo を超えて JavaScript の挙動が必要な箇所にのみコントローラーをアタッチします。検証: ブラウザコンソールで application.getControllerForElementAndIdentifier(el, 'name') がコントローラーインスタンスを返すことを確認します。
5. デグレードモードを検証する — ブラウザの DevTools で JavaScript を無効化する（または Capybara の :rack_test ドライバーで rails test:system を実行する）と、JS なしですべてが維持されることを確認します: フォームが送信され、リンクが遷移し、リロード後もデータが保持されます。

コード例

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 コントローラー

import { Controller } from "@hotwired/stimulus"

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

app/javascript/controllers/index.js に登録します:

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

出力スタイル

Hotwire を実装する際、出力には必ず以下を含める必要があります:

1. プログレッシブベースライン — エンハンスメント前のプレーンな HTML で機能がどのように動作するか。
2. 選択したプリミティブ — Turbo Frame、Turbo Stream、Stimulus、またはその組み合わせと、その理由。
3. DOM コントラクト — フレーム ID、ストリームターゲット、Stimulus コントローラー名、ターゲット、値、アクション。
4. サーバーコントラクト — コントローラーのレスポンスフォーマット、ブロードキャストのトリガー、パーシャル名、および使用時の ActionCable チャンネル/ログの確認。
5. 検証 — コアプロセスのステップ 5 のデグレードモードチェックリストに加え、フレーム、ストリーム、または Stimulus の挙動に対するシステム/ブラウザチェック。
6. 言語 — 明示的に指定されない限り英語。

拡張リソース（プログレッシブディスクロージャー）

これらのファイルは、その特定の内容が必要な場合にのみ読み込んでください:

• EXAMPLES.md — Turbo Frames、Streams、Stimulus パターンの完全な実例が必要な場合に使用します
• references/workflow.md — Hotwire 実装のステップバイステップのワークフローと決定木が必要な場合に使用します

統合

スキル	チェーンするタイミング
write-tests	システムスペックと失敗するインタラクションのカバレッジ向け
apply-stack-conventions	Rails + Hotwire + Tailwind スタックの整合性向け
code-review	UI の挙動とデグレードモードが検証された後