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:

javascript

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

Good:

javascript

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

html

<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:

javascript

connect() {
  this.count = 0
}

Good:

javascript

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.

Bad:

javascript

connect() {
  document.addEventListener("click", this.handler.bind(this))
}

Good:

html

<div data-action="click@document->controller#handler"></div>

Key Patterns

Architecture

Configurable Controllers: Inject dependencies via data attributes
Application Controller: Base class for shared functionality
Mixins: Share behavior via "acts as" relationships
Targetless Controllers: Separate element vs. target manipulation
Namespaced Attributes: Handle arbitrary parameter sets

See:

references/architecture.md

State Management

Use Values API for nearly all state
Leverage change callbacks (
```
[name]ValueChanged
```
)
Keep values serializable
Provide sensible defaults

See:

references/state-management.md

Lifecycle

Use
```
connect()
```
for third-party library initialization
Pair
```
connect()
```
with
```
disconnect()
```
for cleanup
Avoid overloading
```
connect()
```
with state setup
Implement
```
teardown()
```
for Turbo-specific cleanup

See:

references/lifecycle.md

Controller Communication

Three approaches:

Custom Events: Loose coupling, broadcast pattern
Outlets: Direct controller references, structured layouts
Callbacks: Request state from other controllers

Choose based on relationship:

Unknown receivers → Custom events
Known hierarchy → Outlets
Data sharing → Callbacks

See:

references/events-and-interaction.md

SOLID Principles

Single Responsibility: One reason to change
Open-Closed: Extend via inheritance, not modification
Dependency Inversion: Depend on abstractions, inject via config

See:

references/solid-principles.md

DOM & Turbo

Use
```
<template>
```
to restore DOM state
Use
```
requestSubmit()
```
not
```
submit()
```
for forms
Implement global teardown for Turbo caching
Handle Turbo events declaratively

See:

references/dom-and-turbo.md

Error Handling

Create ApplicationController with
```
handleError()
```
method
Integrate with error tracking (Sentry, Honeybadger)
Provide user-friendly messages
Use try-catch for async operations

See:

references/error-handling.md

Quick Reference

Value Types

javascript

static values = {
  url: String,
  count: Number,
  enabled: Boolean,
  items: Array,
  config: Object
}

Event Actions

html

<!-- Element events -->
<div data-action="click->controller#method">

<!-- Global events -->
<div data-action="resize@window->controller#layout">
<div data-action="keydown@document->controller#handleKey">

<!-- Multiple actions -->
<div data-action="click->ctrl1#method1 click->ctrl2#method2">

Custom Events

javascript

// Dispatch
const event = new CustomEvent('name:action', {
  bubbles: true,
  detail: { key: 'value' }
})
this.element.dispatchEvent(event)

// Listen
data-action="name:action->controller#handler"

Outlets

html

<div data-controller="parent"
     data-parent-child-outlet=".child">
  <div class="child" data-controller="child"></div>
</div>

javascript

static outlets = ['child']
this.childOutlets.forEach(outlet => outlet.method())

Lifecycle Hooks

javascript

connect()           // Element connected to DOM
disconnect()        // Element removed from DOM
[name]TargetConnected(element)      // Target added
[name]TargetDisconnected(element)   // Target removed
[name]ValueChanged(value, oldValue) // Value changed
[name]OutletConnected(outlet)       // Outlet connected
[name]OutletDisconnected(outlet)    // Outlet disconnected

Implementation Workflow

When writing a new controller:

Identify responsibility - What single purpose does this serve?
Choose state approach - Use Values API unless non-serializable
Declare static properties - values, targets, classes, outlets
Implement change callbacks - React to value changes
Keep connect() minimal - Only for third-party setup
Use declarative actions - Avoid addEventListener
Handle errors gracefully - Wrap risky operations in try-catch
Test lifecycle - Verify connect/disconnect behavior

When refactoring:

Check Single Responsibility - Split if multiple concerns
Extract configuration - Move hardcoded values to data attributes
Convert to Values API - Replace instance properties with values
Simplify connect() - Move state and listeners out
Use inheritance/mixins - Share common behavior properly
Decouple controllers - Use events/outlets for communication
Add error handling - Implement handleError from ApplicationController

Common Mistakes to Avoid

❌ Hardcoding CSS classes, selectors, or IDs in controllers
❌ Using instance properties for state instead of values
❌ Overloading
```
connect()
```
with state setup and event listeners
❌ Creating "page controllers" that handle multiple concerns
❌ Using
```
addEventListener()
```
without proper cleanup
❌ Calling
```
.bind()
```
separately in connect and disconnect
❌ Using
```
submit()
```
instead of
```
requestSubmit()
```
❌ Modifying base classes instead of extending them
❌ Tight coupling between controllers
❌ Swallowing errors without logging or reporting

Resources

All patterns in this skill come from betterstimulus.com, an opinionated collection of StimulusJS best practices.

For detailed explanations and examples, see:

```
references/architecture.md
```
- Controller design patterns
```
references/state-management.md
```
- Values API usage
```
references/lifecycle.md
```
- Lifecycle best practices
```
references/events-and-interaction.md
```
- Communication patterns
```
references/solid-principles.md
```
- SOLID design principles
```
references/dom-and-turbo.md
```
- DOM manipulation and Turbo
```
references/error-handling.md
```
- Error management

better-stimulus

NPX Install

Tags

SKILL.md Content

Better Stimulus

When to Use This Skill

Core Principles

1. Make Controllers Configurable

2. Use Values API for State

3. Keep Controllers Focused (Single Responsibility)

4. Don't Overuse connect()

5. Register Events Declaratively

Key Patterns

Architecture

State Management

Lifecycle

Controller Communication

SOLID Principles

DOM & Turbo

Error Handling

Quick Reference

Value Types

Event Actions

Custom Events

Outlets

Lifecycle Hooks

Implementation Workflow

Common Mistakes to Avoid

Resources