アプリケーションにStimulusをインストールする

アプリケーションにStimulusをインストールするには、JavaScriptのバンドルに@hotwired/stimulus npm パッケージを追加します。あるいはバンドラーを利用してない場合は、<script type="module">タグを使ってstimulus.js をインポートしてください。

原文

To install Stimulus in your application, add the @hotwired/stimulus npm package to your JavaScript bundle. Or, import stimulus.js in a <script type="module"> tag.

Stimulus for Railsを使う

Stimulus for Railsをimport-mapsと一緒に使用している場合、何もせずとも自動的にapp/javascript/controllersからすべてのコントローラファイルを読み込むようになります。

原文

If you’re using Stimulus for Rails together with an import map, the integration will automatically load all controller files from app/javascript/controllers.

コントローラのファイル名と識別子の対応

コントローラファイルの名前は[identifier]_controller.jsとします。identifierは、HTML内の各コントローラの data-controllerの値に設定する識別子に対応します。

Stimulus for Railsでは、ファイル名の複数の単語をアンダースコアで区切るのが一般的です。コントローラのファイル名のアンダースコアは、識別子のダッシュ(-)に変換されます。

サブフォルダを使用してコントローラを名前空間で区切ることもできます。名前空間を指定したコントローラファイルのパス中のスラッシュは、識別子中の2つのダッシュ(--)に対応します。

お望みであれば、コントローラのファイル名でアンダースコアの代わりにダッシュを使用することもできます。 Stimulus はこれらを同じように扱います。

If your controller file is named…	its identifier will be…
clipboard_controller.js	clipboard
date_picker_controller.js	date-picker
users/list_item_controller.js	users–list-item
local-time-controller.js	local-time

原文

Name your controller files [identifier]_controller.js, where identifier corresponds to each controller’s data-controller identifier in your HTML.

Stimulus for Rails conventionally separates multiple words in filenames using underscores. Each underscore in a controller’s filename translates to a dash in its identifier.

You may also namespace your controllers using subfolders. Each forward slash in a namespaced controller file’s path becomes two dashes in its identifier.

If you prefer, you may use dashes instead of underscores anywhere in a controller’s filename. Stimulus treats them identically.

If your controller file is named…	its identifier will be…
clipboard_controller.js	clipboard
date_picker_controller.js	date-picker
users/list_item_controller.js	users–list-item
local-time-controller.js	local-time

Webpack Helpersを使う

JavaScriptのバンドルにWebpackを使用している場合、@hotwired/stimulus-webpack-helpersパッケージを使用してと、Stimulus for Railsと同じ形式のオートロード動作を得ることができます。まずパッケージを追加し、次のように使用します：

import { Application } from "@hotwired/stimulus"
import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers"

window.Stimulus = Application.start()
const context = require.context("./controllers", true, /\.js$/)
Stimulus.load(definitionsFromContext(context))

原文

If you’re using Webpack as your JavaScript bundler, you can use the @hotwired/stimulus-webpack-helpers package to get the same form of autoloading behavior as Stimulus for Rails. First add the package, then use it like this:

import { Application } from "@hotwired/stimulus"
import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers"

window.Stimulus = Application.start()
const context = require.context("./controllers", true, /\.js$/)
Stimulus.load(definitionsFromContext(context))

その他のビルドシステムを使う

Stimulus は他のビルドシステムでも動作しますが、その場合コントローラのオートロードはサポートされません。代わりに、明示的にアプリケーションインスタンスにコントローラファイルをimportして登録する必要があります：

// src/application.js
import { Application } from "@hotwired/stimulus"

import HelloController from "./controllers/hello_controller"
import ClipboardController from "./controllers/clipboard_controller"

window.Stimulus = Application.start()
Stimulus.register("hello", HelloController)
Stimulus.register("clipboard", ClipboardController)

esbuildのようなビルダーでstimulus-railsを使用している場合、stimulus:manifest:update Rakeタスクと./bin/rails generate stimulus [controller] generatorを使用して、app/javascript/controllers/index.jsにあるコントローラのインデックスファイルを自動的に更新することができます。

原文

Stimulus works with other build systems too, but without support for controller autoloading. Instead, you must explicitly load and register controller files with your application instance:

// src/application.js
import { Application } from "@hotwired/stimulus"

import HelloController from "./controllers/hello_controller"
import ClipboardController from "./controllers/clipboard_controller"

window.Stimulus = Application.start()
Stimulus.register("hello", HelloController)
Stimulus.register("clipboard", ClipboardController)

If you’re using stimulus-rails with a builder like esbuild, you can use the stimulus:manifest:update Rake task and ./bin/rails generate stimulus [controller] generator to keep a controller index file located at app/javascript/controllers/index.js automatically updated.

ビルドシステムを使わない場合

ビルドシステムを使用したくない場合は、<script type="module">タグでStimulusをロードすることもできます：

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <script type="module">
    import { Application, Controller } from "https://unpkg.com/@hotwired/stimulus/dist/stimulus.js"
    window.Stimulus = Application.start()

    Stimulus.register("hello", class extends Controller {
      static targets = [ "name" ]

      connect() {
      }
    })
  </script>
</head>
<body>
  <div data-controller="hello">
    <input data-hello-target="name" type="text">
    …
  </div>
</body>
</html>

原文

If you prefer not to use a build system, you can load Stimulus in a <script type="module"> tag:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <script type="module">
    import { Application, Controller } from "https://unpkg.com/@hotwired/stimulus/dist/stimulus.js"
    window.Stimulus = Application.start()

    Stimulus.register("hello", class extends Controller {
      static targets = [ "name" ]

      connect() {
      }
    })
  </script>
</head>
<body>
  <div data-controller="hello">
    <input data-hello-target="name" type="text">
    …
  </div>
</body>
</html>

Stimulusのデフォルトの属性規則を上書きする

Stimulusが使用するdata-*属性がプロジェクト内の他のライブラリと衝突する場合、Stimulus Applicationを作成する際に上書きして変更することができます。

data-controller
data-action
data-target

これらのStimulusのコア属性はオーバーライドすることができます（参照：schema.ts）：

// src/application.js
import { Application, defaultSchema } from "@hotwired/stimulus"

const customSchema = {
  ...defaultSchema,
  actionAttribute: 'data-stimulus-action'
}

window.Stimulus = Application.start(document.documentElement, customSchema);

原文

In case Stimulus data-* attributes conflict with another library in your project, they can be overridden when creating the Stimulus Application.

data-controller
data-action
data-target

These core Stimulus attributes can be overridden (see: schema.ts):

// src/application.js
import { Application, defaultSchema } from "@hotwired/stimulus"

const customSchema = {
  ...defaultSchema,
  actionAttribute: 'data-stimulus-action'
}

window.Stimulus = Application.start(document.documentElement, customSchema);

エラーハンドリング

Stimulusからのアプリケーションコードへの呼び出しはすべてtry ... catchブロックでラップされます。

あなたのコードがエラーをスローした場合、それは Stimulus によってキャッチされ、コントローラ名、呼び出されたイベントまたはライフサイクル関数などの詳細情報を含め、ブラウザコンソールに記録されます。 window.onerrorを定義したエラー追跡システムを使用している場合、Stimulusはそのシステムにもエラーを渡します。

Application#handleErrorを定義することで、Stimulus がエラーを処理する方法をオーバーライドすることもできます：

// src/application.js
import { Application } from "@hotwired/stimulus"
window.Stimulus = Application.start()

Stimulus.handleError = (error, message, detail) => {
  console.warn(message, detail)
  ErrorTrackingSystem.captureException(error)
}

原文

All calls from Stimulus to your application’s code are wrapped in a try … catch block.

If your code throws an error, it will be caught by Stimulus and logged to the browser console, including extra detail such as the controller name and event or lifecycle function being called. If you use an error tracking system that defines window.onerror, Stimulus will also pass the error on to it.

You can override how Stimulus handles errors by defining Application#handleError:

// src/application.js
import { Application } from "@hotwired/stimulus"
window.Stimulus = Application.start()

Stimulus.handleError = (error, message, detail) => {
  console.warn(message, detail)
  ErrorTrackingSystem.captureException(error)
}

デバッグ

Stimulusアプリケーションをwindow.Stimulusに割り当てている場合、Stimulus.debug = trueでコンソールからデバッグモードをオンにすることができます。このフラグはソースコードでアプリケーションインスタンスを作成するときにも設定できます。

原文

If you’ve assigned your Stimulus application to window.Stimulus, you can turn on debugging mode from the console with Stimulus.debug = true. You can also set this flag when you’re configuring your application instance in the source code.

ブラウザサポート

Stimulusは、すべてのエバーグリーンブラウザ(デスクトップおよびモバイル)をサポートしています。また、Stimulus 3+はInternet Explorer 11をサポートしていません（しかし、その場合@stimulus/polyfillsとStimulus 2を使用することができます）。

原文

Stimulus supports all evergreen, self-updating desktop and mobile browsers out of the box. Stimulus 3+ does not support Internet Explorer 11 (but you can use Stimulus 2 with the @stimulus/polyfills for that).

アプリケーションにStimulusをインストールする

# Stimulus for Railsを使う

# コントローラのファイル名と識別子の対応

# Webpack Helpersを使う

# その他のビルドシステムを使う

# ビルドシステムを使わない場合

# Stimulusのデフォルトの属性規則を上書きする

# エラーハンドリング

# デバッグ

# ブラウザサポート