Stimulus is a JavaScript framework with modest ambitions. It doesn’t seek to take over your entire front-end in fact, it’s not concerned with rendering HTML at all. Instead, it’s designed to augment your HTML with just enough behavior to make it shine. Stimulus pairs beautifully with Turbo to provide a complete solution for fast, compelling applications with a minimal amount of effort.
Stimulus for Rails makes it easy to use this modest framework with the asset pipeline and ES6/ESM in the browser. It uses the 7kb es-module-shim to provide importmap support for all ES6-compatible browsers. This means you can develop and deploy without using any bundling or transpiling at all! Far less complexity, no waiting for compiling.
If you want to use Stimulus with a bundler, you should use Webpacker instead. This gem is purely intended for those who wish to use Stimulus with the asset pipeline using ESM in the browser.
- Add the
stimulus-railsgem to your Gemfile:gem 'stimulus-rails' - Run
./bin/bundle install. - Run
./bin/rails stimulus:install
If using the asset pipeline to manage JavaScript, the last command will:
- Create an example controller in
app/assets/javascripts/controllers/hello_controller.js. - Append the include tags to the
<head>of yourapp/views/layouts/application.html.erb. - Initialize your
importmap.jsoninapp/assets/javascripts/importmap.json.erb. - Ensure JavaScript is included in your
app/assets/config/manifest.jsfile for compilation.
If using Webpacker to manage JavaScript, the last command will:
- Import the controllers directory in the application pack.
- Create a controllers directory at
app/javascripts/controllers. - Create an example controller in
app/javascripts/controllers/hello_controller.js. - Install the Stimulus NPM package.
With the Stimulus include tags added, you'll automatically have activated Stimulus through the controller autoloader. You can now easily add new Stimulus controllers that'll be loaded via ESM dynamic imports.
For example, a more advanced hello_controller could look like this:
// app/assets/javascripts/controllers/hello_controller.js
import { Controller } from "stimulus"
export default class extends Controller {
static targets = [ "name", "output" ]
greet() {
this.outputTarget.textContent = `Hello, ${this.nameTarget.value}!`
}
}And it'll be activated and registered automatically when encountering the data-controller attribute in your DOM:
<div data-controller="hello">
<input data-hello-target="name" type="text">
<button data-action="click->hello#greet">
Greet
</button>
<span data-hello-target="output">
</span>
</div>That's it!
You can add additional libraries needed by your controllers in app/assets/javascripts/libraries using the [email protected] naming convention. These libraries will be added to the dynamically generated importmap (a shim is included with the stimulus_include_tags), so you can reference [email protected] as import Cookie from "cookies".
The libraries must be made for ESM. See https://skypack.dev where you can either directly reference libraries or download them and use them with the ESM conversion.
Stimulus for Rails is released under the MIT License.