Registry / web-framework / stimulus-vite-helpers

stimulus-vite-helpers

library3.1.0jsnpmunverified

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.

web-framework

npm install stimulus-vite-helpers

github ↗package ↗

INSTALL

IMPORT

SIG · STIMULUS-VITE-HELP

stimulus-vite-helpers

web-frameworkjavascriptv3.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

registerControllers

✓ import { registerControllers } from 'stimulus-vite-helpers'

✗ const { registerControllers } = require('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

✓ import { Application } from 'stimulus'

✗ import Stimulus 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

✓ const controllers = import.meta.glob('./**/*_controller.js', { eager: true })

✗ const controllers = require.context('./controllers', true, /_controller\.js$/)

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.

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);

Debug

Known issues

breakingThis 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaThe 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`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'start')

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

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

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.

Upgrade

Version history

3.1.0latest on npm

Audit

Dependencies

stimulusrequiredRuntime dependency for the Stimulus Application instance and controller definitions.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/ElMassimo/stimulus-vite-helpers ↗

packagehttps://www.npmjs.com/package/stimulus-vite-helpers ↗