better-stimulus_skill

Overview

This skill applies Better Stimulus best practices for writing maintainable, reusable StimulusJS controllers that follow SOLID design principles. It codifies patterns for configurable controllers, state management with the Values API, declarative events, and clear lifecycle handling. Use it to standardize controller structure and reduce coupling across your front-end codebase.

How this skill works

The skill inspects controller code and recommends or enforces patterns: externalizing configuration into data attributes, migrating instance state to Stimulus values, and minimizing connect() responsibilities. It highlights communication strategies (custom events, outlets, callbacks), lifecycle pairing (connect/disconnect/teardown), and error-handling via an ApplicationController. Output is practical guidance to refactor controllers toward single responsibility and dependency injection.

When to use it

• When creating new Stimulus controllers to set a consistent architecture
• When refactoring controllers that mix responsibilities or use instance properties for state
• During code reviews to enforce declarative events and Values API usage
• When integrating third-party libraries (Swiper, Chart.js) to scope initialization and cleanup
• When debugging controller-to-controller communication or Turbo-related DOM caching

Best practices

• Externalize hardcoded values to data attributes and static classes to make controllers configurable
• Use static values and valueChanged callbacks for state instead of instance properties
• Keep connect() focused on third-party initialization and feature detection — avoid setting state or adding listeners there
• Register DOM and global events with data-action, not addEventListener, to let Stimulus manage lifecycle
• Prefer custom events, outlets, or callbacks based on relationship: unknown receivers → events; known hierarchy → outlets; direct data requests → callbacks
• Provide an ApplicationController with handleError(), pair connect() with disconnect(), and implement teardown for Turbo caching

Example use cases

• Build a reusable toggle controller that reads its active class from data attributes and exposes a value for state
• Refactor a monolithic page controller into focused controllers that each handle one concern (form, modal, list)
• Integrate Chart.js in a controller using connect() for init and disconnect() for teardown, with chart config passed via data attributes
• Replace document addEventListener usage with data-action declarations and value change callbacks
• Set up inter-controller communication using custom events for broadcasts and outlets for parent-child interactions