stimulus-rails

When using a JavaScript bundler, you must keep app/javascript/controllers/index.js in sync with your controller files. You can do this in two ways:

1. Using the Generator: Run ./bin/rails generate stimulus [controller_name]. This creates the controller file and automatically updates the manifest (index.js).
2. Using the Manifest Task: Run ./bin/rails stimulus:manifest:update. This updates the index.js file to include all existing controllers.

# Create a new controller and update the manifest automatically
./bin/rails generate stimulus hello

# Or just update the manifest manually
./bin/rails stimulus:manifest:update

For Rails 6 applications, the easiest way to install stimulus-rails is using the provided installer. This will automatically detect if you are using importmap-rails or a JavaScript bundler (like jsbundling-rails) and configure your files accordingly.

1. Add the gem to your Gemfile.
2. Install the gem.
3. Run the stimulus installation task.

# Gemfile
gem 'stimulus-rails'

./bin/bundle install
./bin/rails stimulus:install

The stimulus-rails gem automates the registration of JavaScript controllers with your Stimulus application. It scans your controllers directory for files ending in _controller (e.g., hello_controller.js or nested/folder/hello_controller.js) and generates an index.js file that imports and registers them.

Naming Conventions:

• JavaScript Class Name: The file path is converted to a CamelCase class name. For example, nested/folder/hello_controller.js becomes Nested::Folder::Hello (or Nested__Folder__Hello in the generated JS import).
• HTML Identifier (Tag Name): The file path is converted to a kebab-case string used in data-controller attributes. For example, nested/folder/hello_controller.js becomes nested--folder--hello.

A Stimulus controller is a JavaScript class that extends Controller from @hotwired/stimulus. It connects to HTML elements via the data-controller attribute. You can define static targets to easily interact with specific elements within the controller's scope.

// app/javascript/controllers/hello_controller.js
import { Controller } from "@hotwired/stimulus"

// Connects with data-controller="hello"
export default class extends Controller {
  static targets = [ "name", "output" ]

  greet() {
    this.outputTarget.textContent = `Hello, ${this.nameTarget.value}!`
  }
}

If you are using a JavaScript bundler (like jsbundling-rails) and do not want the stimulus-rails gem to automatically add its internal assets to your Sprockets/Propshaft precompilation list, you can remove them in a Rails initializer.

Use the Stimulus::Engine::PRECOMPILE_ASSETS constant to identify the files being added.

# config/initializers/stimulus_assets.rb
Rails.application.configure do
  config.after_initialize do
    config.assets.precompile -= Stimulus::Engine::PRECOMPILE_ASSETS
  end
end

Use the Stimulus Rails generator to create a new Stimulus controller file in app/javascript/controllers/. The generator automatically handles naming conventions and, by default, updates the Stimulus manifest to ensure the new controller is discoverable.

To prevent the generator from updating the Stimulus manifest (for example, if you are managing imports manually), use the --skip-manifest flag.

# Standard usage (updates manifest)
rails generate stimulus <name>

# Usage without updating the manifest
rails generate stimulus <name> --skip-manifest

To register new Stimulus controllers in your application, you must update the auto-generated index.js file. This is done by running the following command in your terminal:

bin/rails stimulus:manifest:update

You should run this command whenever you:

1. Add a new controller file manually.
2. Create a new controller using the generator: ./bin/rails generate stimulus controllerName.

# Run this command to sync your JavaScript index file with your new controllers
./bin/rails stimulus:manifest:update