Stimulus入門：コントローラ・ターゲット・アクション設計をやさしく理解する完全ガイド

1. Stimulusとは？Railsと相性が良い理由

1. Stimulusとは？Railsと相性が良い理由

Stimulusは、RailsのHotwireを構成するJavaScriptフレームワークの一つです。 最大の特徴は「HTMLを主役にする」点です。 難しい設定ファイルや大量のコードを書かなくても、HTMLに属性を書くだけで動きを追加できます。 プログラミング未経験の方にとっては、スイッチを押したら電気がつくような感覚で理解できます。 Railsの考え方である決まりごとを守れば迷わない設計とも相性が良く、画面のちょっとした動きを安全に実装できます。

2. Stimulusの基本構造：コントローラとは何か

2. Stimulusの基本構造：コントローラとは何か

Stimulusで最初に登場するのがコントローラです。 コントローラは「このHTMLの動きをまとめて管理する箱」のような存在です。 例えば、リモコンがテレビ専用であるように、Stimulusのコントローラも担当するHTMLが決まっています。 Railsではapp/javascript/controllersにファイルを作成します。

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    console.log("接続されました")
  }
}

このconnectは、HTMLとコントローラがつながった瞬間に呼ばれる処理です。 「画面に現れたら動く準備をする」と覚えると理解しやすくなります。

3. ターゲット：操作したい場所を名前で指定する

3. ターゲット：操作したい場所を名前で指定する

ターゲットは「操作したい場所に名前を付ける仕組み」です。 付箋にメモを書いて貼るイメージをすると分かりやすいです。 HTML側でdata-○○-targetを使って指定します。

<div data-controller="counter">
  <span data-counter-target="number">0</span>
</div>

JavaScript側では、その名前を使って簡単にアクセスできます。 難しいDOM操作を覚える必要がありません。

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

4. アクション：クリックなどの動作を結びつける

4. アクション：クリックなどの動作を結びつける

アクションは「何かしたら何をするか」を決める仕組みです。 ボタンを押したらベルが鳴る、という因果関係をそのまま書けます。 HTMLではdata-actionを使います。

<button data-action="click->counter#increment">
  増やす
</button>

increment() {
  this.numberTarget.textContent++
}

「clickしたらcounterコントローラのincrementを実行する」 と、日本語の文章のように読めるのがStimulusの強みです。

5. コントローラ設計の基本ルール

5. コントローラ設計の基本ルール

Stimulusでは、一つのコントローラに多くの役割を持たせすぎないことが重要です。 リモコン一つでテレビとエアコンを操作しないのと同じです。 画面の部品ごとにコントローラを分けると、読みやすく壊れにくくなります。 また、HTMLの構造をそのまま活かす設計を意識すると、Railsらしいコードになります。

6. よくある失敗とベストプラクティス

6. よくある失敗とベストプラクティス

初心者がつまずきやすいのは、名前の付け方です。 コントローラ名・ターゲット名・アクション名は、役割が分かる名前にしましょう。 また、CSSのクラスと混同しないように注意が必要です。 Stimulusは見た目ではなく「動き」を担当します。 役割を分けて考えることで、コードが整理されます。

7. ViewComponentとStimulusを組み合わせる考え方

7. ViewComponentとStimulusを組み合わせる考え方

ViewComponentは「見た目の部品」を管理する仕組みです。 Stimulusは「動き」を担当します。 この二つを組み合わせると、HTML・見た目・動きが整理され、 後から読み返しても理解しやすいコードになります。 部品ごとに責任を分ける考え方は、長く使えるRailsアプリを作る土台になります。