better-stimulus

Better Stimulus

Apply opinionated best practices from betterstimulus.com when writing or refactoring Stimulus controllers. These patterns emphasize code reusability, proper separation of concerns, and SOLID design principles.

When to Use This Skill

Invoke this skill when:

• Writing new Stimulus controllers
• Refactoring existing Stimulus code
• Reviewing Stimulus controller architecture
• Debugging inter-controller communication
• Integrating third-party JavaScript libraries
• Implementing form submission logic
• Managing controller state
• Setting up Turbo integration

Core Principles

1. Make Controllers Configurable

Externalize hardcoded values into data attributes rather than embedding them in controller logic.

Bad:

toggle() {
  this.element.classList.toggle("active")
}

Good:

static classes = ["active"]
toggle() {
  this.element.classList.toggle(this.activeClass)
}

<div data-controller="toggle" data-toggle-active-class="active"></div>

2. Use Values API for State

Store controller state in Stimulus values, not instance properties, to leverage reactivity and DOM persistence.

Bad:

connect() {
  this.count = 0
}

Good:

static values = { count: Number }
countValueChanged(count) {
  this.updateDisplay()
}

3. Keep Controllers Focused (Single Responsibility)

Each controller should have one reason to change. Split controllers that mix concerns.

Ask: "What would cause this controller to change?" If multiple unrelated reasons, split it.

4. Don't Overuse connect()

Use connect() for:

• Instantiating third-party plugins (Swiper, Chart.js, etc.)
• Feature detection/browser capabilities

Don't use connect() for:

• Setting up state (use Values API)
• Adding event listeners (use data-action)

5. Register Events Declaratively

Use data-action attributes instead of addEventListener() to let Stimulus manage lifecycle.