better-stimulus

Better Stimulus

Opinionated StimulusJS best practices sourced directly from betterstimulus.com / julianrubisch/better-stimulus.

---

ARCHITECTURE

1. Application Controller

Create a base ApplicationController that all controllers inherit from. Use it to share lifecycle hooks and utility methods across the app.

// application_controller.js
import { Controller } from "@hotwired/stimulus";
export default class extends Controller {
  // shared helpers, error handling, etc.
}

// custom_controller.js
import ApplicationController from "./application_controller";
export default class extends ApplicationController {
  // specialized behavior
}

When NOT to use inheritance: Ask whether the shared behavior is a specialization ("is a") → use inheritance; a role ("acts as a") → use mixins; a collaborator ("has a") → use composition.

---

2. Configurable Controllers (Late Binding)

Never hardcode dependencies (CSS classes, selectors, IDs) inside controllers. Use the Classes API, Values API, or dataset attributes so controllers are reusable.

Bad:

toggle(e) {
  this.element.classList.toggle("active"); // hardcoded class
}

Good:

<a data-controller="toggle" data-action="click->toggle#toggle" data-toggle-active-class="active">

static classes = ["active"];

toggle(e) {
  e.preventDefault();
  this.element.classList.toggle(this.activeClass);
}

Rationale: Late binding of dependencies ensures controllers are reusable across multiple use cases without modification.

---

3. Mixins Over Inheritance for Shared Behavior

When behavior is a role (not a specialization), use mixins instead of inheritance.

Bad — extending a concrete controller:

import OverlayController from "./overlay_controller";
export default class extends OverlayController { ... }

Good — mixin pattern:

// mixins/useOverlay.js
export const useOverlay = controller => {
  Object.assign(controller, {
    showOverlay(e) { ... },
    hideOverlay(e) { ... }
  });
};

// dropdown_controller.js
import { useOverlay } from "./mixins/useOverlay";
export default class extends Controller {
  connect() {
    useOverlay(this);
  }
}