Symfony Stimulus Bundle

When you install a Symfony UX package (e.g., @symfony/ux-chartjs), the bundle automatically makes its controllers available through a combination of Node package aliasing and a JSON manifest.

1. Node Aliasing: The package is added to package.json as a file reference pointing to your vendor/ directory (e.g., '@symfony/ux-chartjs': 'file:vendor/symfony/ux-chartjs/assets').
2. Manifest Registration: The package's controllers are added to assets/controllers.json.
3. Automatic Loading: Your assets/stimulus_bootstrap.js (configured for AssetMapper, Encore, or Reprise) automatically registers controllers found in assets/controllers/ AND those listed in assets/controllers.json.

Example: Using a UX controller in Twig If a package provides a controller named @symfony/ux-chartjs/chart, it is internally mapped to symfony--ux-chartjs--chart. You can use the original name in Twig with the stimulus_controller() helper, and it will be normalized:

<div {{ stimulus_controller('@symfony/ux-chartjs/chart') }}>
    <!-- Renders as: <div data-controller="symfony--ux-chartjs--chart"> -->
</div>

By default, all registered controllers load on every page. To prevent eager loading of controllers from one area (e.g., admin) into another (e.g., public site), you can use Reprise to create scoped builds.

To achieve this, give the specific area its own build configuration and point the Reprise plugin to a dedicated controllers directory and a specific controllers.json file.

After configuring the build, register it on the PHP side under reprise.builds. This allows Symfony Twig helpers to target that specific build using the build argument.

// vite.config.admin.ts  -- run with `vite build --config vite.config.admin.ts`
import { defineConfig } from 'vite'
import Symfony from '@symfony/reprise/vite'

export default defineConfig({
  input: {
    admin: './assets/admin.js',
  },
  plugins: [
    Symfony({
      outputPath: 'public/admin-build',
      publicPath: '/admin-build/',
      stimulus: {
        controllersJson: 'assets/admin/controllers.json',
        controllersDir: 'assets/admin/controllers',
      },
    }),
  ],
})

// assets/admin.js
import { startStimulusApp } from '@symfony/reprise/stimulus'

const app = startStimulusApp()

If you are using Webpack Encore, you can scope controllers by passing a Webpack context to startStimulusApp(). This allows an entry point to load only the controllers within a specific directory.

Single Scoped Entry Point

To load only controllers under a specific path (e.g., ./controllers/admin), pass a require.context to startStimulusApp. If you rely on lazy loading, ensure you include the @symfony/stimulus-bridge/lazy-controller-loader! prefix in the context path.

Loading Multiple Contexts into One Application

If you have shared controllers and area-specific controllers, you can load multiple contexts into a single application instance using app.load() and definitionsFromContext from @hotwired/stimulus-webpack-helpers.

// Single scoped entry point
import { startStimulusApp } from '@symfony/stimulus-bridge';

export const app = startStimulusApp(require.context(
    '@symfony/stimulus-bridge/lazy-controller-loader!./controllers/admin',
    true,
    /\.[jt]sx?$/
));

// Loading multiple contexts
import { startStimulusApp } from '@symfony/stimulus-bridge';
import { definitionsFromContext } from '@hotwired/stimulus-webpack-helpers';

const app = startStimulusApp();

app.load(definitionsFromContext(require.context('./controllers/common', true)));
app.load(definitionsFromContext(require.context('./controllers/admin', true)));

The Stimulus bundle distinguishes between two types of controller loading to optimize performance:

Eager Controllers

Eager controllers are registered immediately when loadControllers() is called. These are typically controllers that are required on almost every page or are part of the core application logic.

Lazy Controllers

Lazy controllers are loaded only when they are actually needed in the DOM. The StimulusLazyControllerHandler manages this via two mechanisms:

1. Initial Scan: It scans the existing DOM for data-controller attributes and triggers the loading of the corresponding lazy modules.
2. Mutation Observation: It sets up a MutationObserver to watch for new elements being added to the DOM or existing elements having their data-controller attributes modified (common in applications using Turbo or Live Components).

Once a lazy controller has been requested and its module is loaded, the loader disconnects the observer if no more lazy controllers remain in the registry to prevent unnecessary performance overhead during frequent DOM mutations.