Stimulus for Rails
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.
Installation
- Add the
stimulus-rails
gem to your Gemfile:gem 'stimulus-rails'
- Run
./bin/bundle install
. - Run
./bin/rails stimulus:install
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.json
inapp/assets/javascripts/importmap.json.erb
. - Ensure JavaScript is included in your
app/config/manifest.js
file for compilation.
Usage
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 library@1.0.0.js
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 cookies@0.5.6.js
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.
License
Stimulus for Rails is released under the MIT License.