Stimulus Vite Helpers

3.1.0 · active · verified Sun Apr 19

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.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'start')
```
cause The `Application` object from 'stimulus' was not correctly imported or is undefined, likely due to a CommonJS/ESM mismatch or incorrect Stimulus installation.

fix Ensure `import { Application } from 'stimulus'` is correct and Stimulus is properly installed as an ESM module. Check your `package.json` for `stimulus`.
```
SyntaxError: 'import.meta' is only allowed in an ES module
```
cause Your JavaScript file containing `import.meta.glob` is being treated as a CommonJS module by your environment, not an ES module.

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.
```
Uncaught ReferenceError: process is not defined
```
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.

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.

Warnings

breaking 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.
Fix: Migrate your project to use ESM and Vite. If using a different bundler, seek specific plugins or alternative approaches for Stimulus controller registration.
gotcha 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.
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.
gotcha 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.
Fix: Always use `{ eager: true }` when defining the `controllers` glob for `registerControllers` to ensure all controllers are immediately available upon application start.
gotcha 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.
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`.

Install

npm install stimulus-vite-helpers npm
yarn add stimulus-vite-helpers yarn
pnpm add stimulus-vite-helpers pnpm

Imports

registerControllers
wrong:
```
const { registerControllers } = require('stimulus-vite-helpers')
```
correct:
```
import { registerControllers } from 'stimulus-vite-helpers'
```
This package is ESM-first and expects `import` syntax. CJS `require` is not supported for direct use in Vite environments. Types are included.
Application
wrong:
```
import Stimulus from 'stimulus'
```
correct:
```
import { Application } from 'stimulus'
```
While not part of this package, `Application` is the primary co-import for `stimulus-vite-helpers` usage. Stimulus itself uses named exports.
import.meta.glob
wrong:
```
const controllers = require.context('./controllers', true, /_controller\.js$/)
```
correct:
```
const controllers = import.meta.glob('./**/*_controller.js', { eager: true })
```
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.

Quickstart

Demonstrates initializing a Stimulus application and registering all controllers found via Vite's `import.meta.glob`.

import { Application } from 'stimulus';
import { registerControllers } from 'stimulus-vite-helpers';

// Initialize the Stimulus application
const application = Application.start();

// Use Vite's import.meta.glob to discover all Stimulus controllers.
// The pattern './**/*_controller.js' will match all files ending in '_controller.js'
// recursively from the current directory. { eager: true } ensures they are imported immediately.
const controllers = import.meta.glob('./**/*_controller.js', { eager: true });

// Register the discovered controllers with the Stimulus application.
registerControllers(application, controllers);

console.log('Stimulus application started with controllers:', Object.keys(controllers).length);

view raw JSON →