{"id":21270,"library":"esbuild-plugin-stimulus","title":"esbuild-plugin-stimulus","description":"An esbuild plugin for automatically loading Stimulus controllers from a folder, inspired by the webpack helpers. Version 0.2.0 is current and stable. It maps controller file names to Stimulus identifier conventions (e.g., `users/list_item_controller.js` becomes `users--list-item`). Ships TypeScript declarations. No breaking changes known, but usage requires both esbuild and Stimulus (or @hotwired/stimulus). Lightweight, single-purpose plugin with no runtime dependencies.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/zombiezen/esbuild-plugin-stimulus","tags":["javascript","esbuild","plugin","stimulus","typescript"],"install":[{"cmd":"npm install esbuild-plugin-stimulus","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-stimulus","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-stimulus","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency; provides the plugin API and build system","package":"esbuild","optional":false},{"reason":"runtime peer; needed for Application and types","package":"@hotwired/stimulus","optional":true}],"imports":[{"note":"Uses CommonJS with named export; no default export. For ESM, use const { stimulusPlugin } = await import('esbuild-plugin-stimulus').","wrong":"import stimulusPlugin from 'esbuild-plugin-stimulus'","symbol":"stimulusPlugin","correct":"const { stimulusPlugin } = require('esbuild-plugin-stimulus')"},{"note":"Named export from a virtual module with stimulus: prefix. Path is relative to project root.","wrong":"import definitions from 'stimulus:./controllers'","symbol":"definitions","correct":"import { definitions } from 'stimulus:./controllers'"},{"note":"Type import for the Definition type used in the .d.ts declaration. Only needed in TypeScript.","wrong":"","symbol":"Definition","correct":"import type { Definition } from '@hotwired/stimulus'"}],"quickstart":{"code":"// build.js (CommonJS)\nconst esbuild = require('esbuild');\nconst { stimulusPlugin } = require('esbuild-plugin-stimulus');\n\nesbuild.build({\n  entryPoints: ['app.js'],\n  bundle: true,\n  outfile: 'dist/bundle.js',\n  plugins: [stimulusPlugin()],\n}).catch(() => process.exit(1));\n\n// app.js (ESM)\nimport { Application } from '@hotwired/stimulus';\nimport { definitions } from 'stimulus:./controllers';\n\nconst app = Application.start();\napp.load(definitions);\n\n// esbuild-plugin-stimulus.d.ts (optional, for TypeScript)\ndeclare module 'stimulus:*' {\n  import type { Definition } from '@hotwired/stimulus';\n  export const definitions: Definition[];\n}","lang":"javascript","description":"Sets up esbuild with the plugin and uses the virtual module to load controllers from the ./controllers directory."},"warnings":[{"fix":"Always use `from 'stimulus:./controllers'` (with the prefix) in your application code.","message":"Plugin requires the `stimulus:` import prefix to work; using a bare path will not trigger the plugin.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure the path after `stimulus:` resolves from your project root. For example, if your app is in `src/app.js` and controllers in `src/controllers`, use `'stimulus:./src/controllers'`.","message":"The import path in `stimulus:./controllers` is relative to the project root (where esbuild is invoked), not relative to the importing file.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Replace `import { Application } from 'stimulus'` with `import { Application } from '@hotwired/stimulus'`.","message":"If you are using the older 'stimulus' package (before it was renamed to @hotwired/stimulus), the import paths may still work, but it is recommended to update.","severity":"deprecated","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Add a `esbuild-plugin-stimulus.d.ts` file (as shown in the quickstart) to your project.","cause":"Missing type declaration file for the virtual module.","error":"TypeScript error: Cannot find module 'stimulus:./controllers' or its corresponding type declarations."},{"fix":"Add `stimulusPlugin()` to the `plugins` array in your esbuild configuration.","cause":"The stimulus plugin is not included in the esbuild plugins array.","error":"Error: [esbuild] Plugin 'stimulus' returned an error: Could not resolve 'stimulus:./controllers'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}