esbuild-plugin-stimulus

esbuild-plugin-stimulus is an esbuild plugin that automatically discovers and registers Hotwire Stimulus controllers from a directory, so you don’t have to wire each one up by hand. Drop a file like controllers/users/list_item_controller.js into your controllers folder and it becomes available as the Stimulus identifier users--list-item.

The plugin resolves a virtual stimulus: import (e.g. import { definitions } from 'stimulus:./controllers') that expands to the full set of controller definitions at build time, mirroring the ergonomics of the webpack Stimulus loader while using esbuild’s fast bundling.

What You Get

• A stimulusPlugin() you add to your esbuild plugins array
• A virtual stimulus:./controllers import that resolves to all controller definitions
• Automatic filename-to-identifier mapping (nested folders become -- separators)
• Support for .js/.jsx/.ts/.tsx controllers with TypeScript declaration support

Common Use Cases

• Bundling a Hotwire/Stimulus front end with esbuild instead of webpack
• Auto-registering a growing set of Stimulus controllers without manual imports
• Migrating a Rails/Hotwire app’s asset pipeline to esbuild

Under The Hood

Architecture - The entire plugin lives in src/index.ts. It exports stimulusPlugin() returning an esbuild Plugin that registers onResolve/onLoad callbacks for the stimulus: namespace. parseControllerName strips known extensions and -controller/_controller suffixes and converts path segments into Stimulus identifiers (nested folders become --), then the loader reads the target directory with a promisified fs.readdir and emits a generated module exporting the definitions array.

Tech Stack - TypeScript compiled to CommonJS (build/index.js), depending only on esbuild (peer/dev) and Node’s path/fs/util. Tooling includes Jest, a tsconfig.json, and a Nix shell.nix.

Code Quality - The repo includes a Jest config and src/index.test.ts colocated with the implementation, giving unit coverage of the name-parsing and discovery logic. Code is small, well-licensed per file, and readable.

API Design - The public API is a single factory function with sensible defaults, and usage is a two-line change to an esbuild config plus one stimulus: import, matching the familiar webpack loader pattern. A documented TypeScript declaration snippet makes the virtual import type-safe.