@emaia/stimulus-dynamic-loader

Stimulus Dynamic Loader

Lazy load your Stimulus controllers on demand with Vite's glob imports. Automatically registers controllers as they appear in the DOM.

Features

• Lazy Loading: Controllers are loaded only when needed
• Turbo Integration: Automatically registers controllers on Turbo events
• Dynamic DOM: Watches for new elements with MutationObserver
• Zero Config: Works out of the box with Vite's glob imports
• Type Safe: Full TypeScript support

Installation

npm install @emaia/stimulus-dynamic-loader

Usage

Basic Setup

import { Application } from "@hotwired/stimulus";
import { registerControllers } from "@emaia/stimulus-dynamic-loader";

const Stimulus = Application.start();

const controllers = import.meta.glob("./**/*_controller.{js,ts}", { 
  eager: false 
});

registerControllers(Stimulus, controllers)

Custom Configuration

const options = {
  // Custom Turbo events (optional)
  turboEvents: [
    "turbo:load",
    "turbo:frame-render",
  ],
  
  // Custom debounce wait time in ms (optional, default: 100)
  debounceWait: 50,
};

registerControllers(Stimulus, controllers, options)

With Cleanup

const loader = new StimulusDynamicLoader({
  application: Stimulus,
  controllers: controllers,
});

// Later, if you need to disconnect
loader.disconnect();

How It Works

1. Controller Discovery: Scans the DOM for [data-controller] attributes
2. Path Mapping: Creates a map of controller names to file paths
3. Lazy Loading: Dynamically imports controllers only when found in the DOM
4. Auto Registration: Registers controllers with Stimulus automatically
5. Event Listening: Responds to Turbo navigation and DOM mutations
6. Debouncing: Prevents excessive registration attempts

Behavior

• Controllers are loaded only once per name
• Duplicate controller names trigger a console warning
• Failed imports are logged with detailed error messages
• Case-insensitive controller name matching
• Automatically handles Turbo frame renders and stream updates
• MutationObserver watches for dynamically added elements

Extensions and Structure

'./dropdown_controller.ts' → 'dropdown'
'./dropdown_controller.js' → 'dropdown'
'./dropdown_controller.tsx' → 'dropdown'
'./dropdown_controller.mjs' → 'dropdown'

// Flat
'./users_controller.ts' → 'users'

// Controllers folder
'./controllers/users_controller.ts' → 'users'

// Components folder
'./components/dropdown_controller.ts' → 'dropdown'

// Deep nested
'./controllers/admin/settings/billing_controller.ts' → 'admin--settings--billing'

<!-- Flat -->
<div data-controller="users"></div>

<!-- Nested -->
<div data-controller="admin--users"></div>
<div data-controller="admin--settings--billing"></div>

Requirements

• @hotwired/stimulus ^3.0.0
• Vite or similar bundler with import.meta.glob support

License

MIT