{"id":12078,"library":"stimulus-vite-helpers","title":"Stimulus Vite Helpers","description":"stimulus-vite-helpers is a utility package designed to simplify the registration of Stimulus.js controllers within applications that utilize Vite.js as their build tool. It provides a `registerControllers` helper function, which works in conjunction with Vite's `import.meta.glob` feature to automatically discover and register controllers across your project. The current stable version is 3.1.0, and the project appears to follow a release cadence tied to new features or improvements in Stimulus or Vite ecosystems. Key differentiators include its tight integration with Vite's native glob importing, streamlining a common Stimulus setup pattern, and its origin from the Jumpstart Rails with Vite.js template, implying robust integration with Rails applications using Vite. It does not provide HMR itself but suggests `vite-plugin-stimulus-hmr` for that functionality. This library is crucial for those building modern web applications with the Stimulus framework and Vite bundler, especially in Ruby on Rails contexts where `vite_rails` is often used.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/ElMassimo/stimulus-vite-helpers","tags":["javascript","stimulus","stimulusjs","rails","ruby","vite","vite-plugin","vitejs","typescript"],"install":[{"cmd":"npm install stimulus-vite-helpers","lang":"bash","label":"npm"},{"cmd":"yarn add stimulus-vite-helpers","lang":"bash","label":"yarn"},{"cmd":"pnpm add stimulus-vite-helpers","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for the Stimulus Application instance and controller definitions.","package":"stimulus","optional":false}],"imports":[{"note":"This package is ESM-first and expects `import` syntax. CJS `require` is not supported for direct use in Vite environments. Types are included.","wrong":"const { registerControllers } = require('stimulus-vite-helpers')","symbol":"registerControllers","correct":"import { registerControllers } from 'stimulus-vite-helpers'"},{"note":"While not part of this package, `Application` is the primary co-import for `stimulus-vite-helpers` usage. Stimulus itself uses named exports.","wrong":"import Stimulus from 'stimulus'","symbol":"Application","correct":"import { Application } from 'stimulus'"},{"note":"Vite's `import.meta.glob` is a build-time feature for glob importing modules, replacing webpack's `require.context`. The `eager: true` option ensures modules are loaded immediately, which is typically required for Stimulus registration.","wrong":"const controllers = require.context('./controllers', true, /_controller\\.js$/)","symbol":"import.meta.glob","correct":"const controllers = import.meta.glob('./**/*_controller.js', { eager: true })"}],"quickstart":{"code":"import { Application } from 'stimulus';\nimport { registerControllers } from 'stimulus-vite-helpers';\n\n// Initialize the Stimulus application\nconst application = Application.start();\n\n// Use Vite's import.meta.glob to discover all Stimulus controllers.\n// The pattern './**/*_controller.js' will match all files ending in '_controller.js'\n// recursively from the current directory. { eager: true } ensures they are imported immediately.\nconst controllers = import.meta.glob('./**/*_controller.js', { eager: true });\n\n// Register the discovered controllers with the Stimulus application.\nregisterControllers(application, controllers);\n\nconsole.log('Stimulus application started with controllers:', Object.keys(controllers).length);","lang":"typescript","description":"Demonstrates initializing a Stimulus application and registering all controllers found via Vite's `import.meta.glob`."},"warnings":[{"fix":"Migrate your project to use ESM and Vite. If using a different bundler, seek specific plugins or alternative approaches for Stimulus controller registration.","message":"This package is designed for ESM (ECMAScript Modules) environments and Vite. It will not work directly with CommonJS setups or older bundlers like Webpack's `require.context` without significant transpilation or shim layers. Ensure your project is configured for ESM.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure your project is built and served using Vite. If migrating away from Vite, you will need to replace `import.meta.glob` with an equivalent mechanism for your new bundler.","message":"The `import.meta.glob` function is a Vite-specific API. Using it implies a dependency on Vite for bundling. This code will not run outside of a Vite-processed build without errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `{ eager: true }` when defining the `controllers` glob for `registerControllers` to ensure all controllers are immediately available upon application start.","message":"The `eager: true` option in `import.meta.glob` is critical for Stimulus. Without it, controllers will be dynamically imported only when first used, which might lead to race conditions or controllers not being registered in time for the initial page load.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify your glob pattern matches the actual file structure of your Stimulus controllers. Use specific paths if your controllers are not in a recursive subdirectory, e.g., `./controllers/*.js`.","message":"The glob pattern `./**/*_controller.js` is relative to the file where `import.meta.glob` is called. Incorrect paths or patterns will result in controllers not being found or unexpected files being included, leading to runtime errors or missing functionality.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `import { Application } from 'stimulus'` is correct and Stimulus is properly installed as an ESM module. Check your `package.json` for `stimulus`.","cause":"The `Application` object from 'stimulus' was not correctly imported or is undefined, likely due to a CommonJS/ESM mismatch or incorrect Stimulus installation.","error":"TypeError: Cannot read properties of undefined (reading 'start')"},{"fix":"Ensure your file ends with `.js` and your `package.json` contains `\"type\": \"module\"`, or explicitly name the file `.mjs` to force ES module interpretation. Verify your Vite configuration is correct.","cause":"Your JavaScript file containing `import.meta.glob` is being treated as a CommonJS module by your environment, not an ES module.","error":"SyntaxError: 'import.meta' is only allowed in an ES module"},{"fix":"While `stimulus-vite-helpers` itself doesn't directly use `process`, ensure any other dependencies or custom code intended for browser use do not rely on `process` or other Node.js globals without Vite's `define` configuration for browser compatibility.","cause":"This error typically occurs when Node.js-specific globals or environment variables are accessed in a browser environment without proper polyfilling or Vite configuration.","error":"Uncaught ReferenceError: process is not defined"}],"ecosystem":"npm"}