Rails Stimulus

You are a Rails developer building interactive UIs. The user wants to create dynamic, real-time components using Hotwire (Turbo + Stimulus) without writing JavaScript frameworks.

What to check first

• Run rails -v to confirm Rails 6.1+ (Hotwire support included by default)
• Check Gemfile — ensure hotwire-rails is present (bundle list | grep hotwire)
• Verify app/javascript/controllers directory exists (Stimulus controller location)

Steps

1. Generate a Stimulus controller with rails generate stimulus controller_name — this creates app/javascript/controllers/controller_name_controller.js
2. Define the controller class extending Controller and add a connect() lifecycle hook that runs when the element enters the DOM
3. Create public methods in the controller — these become data-action targets (e.g., toggleMenu() called via data-action="click->controller#toggleMenu")
4. Use data-target="controller.elementName" on HTML elements to reference them in the controller as this.elementNameTarget
5. Import and nest the Stimulus controller in your Rails view with <div data-controller="controller-name">
6. Add data-action="event->controller#method" bindings to trigger controller methods (e.g., data-action="click->counter#increment")
7. Use Turbo frames (<turbo-frame id="unique-id">) to wrap content that should update without full page reload via link_to, and respond with Turbo Stream responses
8. For form submissions, add data-action="submit->form#submit" to forms and handle with event.preventDefault() to use Fetch API with Rails respond_to :turbo_stream

Code

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

export default class extends Controller {
  // Define targets and values
  static targets = ["count", "output"]
  static values = { step: Number }

  connect() {
    // Runs when element with data-controller="counter" enters DOM
    console.log("Counter controller connected")
    this.currentCount = 0
  }

  increment(event) {
    event.preventDefault()
    this.currentCount += this.stepValue || 1
    this.updateDisplay()
  }

  decrement(event) {
    event.preventDefault()
    this.currentCount -= this.stepValue || 1
    this.updateDisplay()
  }

  reset(event) {
    event.preventDefault()
    this.currentCount = 0
    this.updateDisplay()
  }

  updateDisplay() {
    // Access targets: this.countTarget, this.outputTarget
    this.outputTarget.textContent = `Count: ${this.currentCount}`
    this.countTarget.value = this.currentCount
  }

  disconnect() {
    //

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change