A Claude Code plugin that applies opinionated **StimulusJS best practices** sourced from [betterstimulus.com](https://www.betterstimulus.com). Use it whenever writing, reviewing, debugging, or refactoring Stimulus controllers. --- ## What Is This? A Claude Code skill that: - **Writes** Stimulus controllers that follow the Values API, Classes API, and Outlets patterns - **Reviews** existing controllers against a concrete best-practices checklist - **Refactors** anti-patterns such as hardcoded selectors, instance-variable state, and manual `addEventListener` calls - **Applies** SOLID principles adapted to Stimulus (Single Responsibility, Open-Closed, Dependency Inversion) - **Integrates** with Turbo — teardown before caching, restoring DOM state, form interception The skill is triggered by mentions of `data-controller`, `data-action`, `data-target`, `data-values`, outlets, lifecycle callbacks, Hotwire patterns, or Turbo-and-Stimulus integration. --- ## Quick Start ### 1. Add the Marketplace ```bash /plugin marketplace add maquina-app/rails-claude-code ``` ### 2. Install the Plugin ```bash /plugin install better-stimulus@maquina ``` ### 3. Ask for a Review or Refactor ``` > Review my dropdown_controller.js against Stimulus best practices > Refactor this controller to use the Values API instead of instance variables > Write a Stimulus controller that toggles a panel with late binding ``` --- ## What It Enforces | Area | Best Practice | |------|--------------| | State | Use the Values API as the single source of truth, not instance variables | | CSS classes | Store in `static classes`, never hardcode strings | | Events | Declare in `data-action` markup, not `addEventListener` in `connect()` | | Dependencies | Late binding via Values / Classes / dataset — no hardcoded selectors | | Composition | Prefer mixins for roles, inheritance only for specializations | | Inter-controller | Outlets for direct calls, custom events for broadcast | | Third-party libs | Initialize in `connect()`, destroy in `disconnect()` | | Turbo | Implement `teardown()` wired to `turbo:before-cache` when mutating DOM | | SRP | Split controllers that act on both `this.element` and targets | A full pre-commit checklist ships with the plugin so Claude can verify any new controller before handing it back. --- ## Usage Examples ### Review an Existing Controller ``` > Review app/javascript/controllers/modal_controller.js ``` The skill checks for state in instance variables, hardcoded CSS classes, manual event listeners, mixed `element`/`target` responsibilities, and missing Turbo teardown. ### Refactor Toward the Values API ``` > Refactor this controller so state lives in values, not this.open ``` The skill moves state into `static values`, adds a `*ValueChanged` callback, and updates markup to include the new data attributes. ### Write a New Controller with Late Binding ``` > Write a toggle controller that uses data-toggle-active-class for styling ``` The skill produces a controller that reads its active class via the Classes API so the same code works anywhere the markup declares a class. ### Apply Hotwire Patterns ``` > This controller mutates the DOM — add a teardown for Turbo caching ``` The skill adds a `teardown()` method and wires it to `turbo:before-cache` at the application level. --- ## Reference Material The plugin ships with two reference files the skill consults on demand: | Reference | Purpose | |-----------|---------| | `references/cookbook.md` | Copy-paste-ready controllers: faceted search, refresh-when-visible, auto sort, dark mode, radio dropdown | | `references/solid.md` | SOLID principles adapted to Stimulus with examples and rationale | --- ## Package Contents ``` better-stimulus/ └── skills/better-stimulus/ ├── SKILL.md # Main skill └── references/ ├── cookbook.md # Ready-to-use controller patterns ├── inter-controller.md # Outlets, callbacks, custom events ├── error-handling.md # Global error handler └── solid.md # SOLID principles for Stimulus ``` --- ## Team Installation Add to your project's `.claude/settings.json`: ```json { "extraKnownMarketplaces": { "maquina": { "source": { "source": "github", "repo": "maquina-app/rails-claude-code" } } }, "enabledPlugins": [ "better-stimulus@maquina" ] } ``` --- ## Next Steps

GitHub Repository

View source code and contribute.

betterstimulus.com

The original collection of Stimulus best practices.

Maquina UI Standards

Pair with component-level UI guidance.