Symfony Stimulus Bridge

The Symfony Stimulus Bridge wires Hotwired Stimulus into a Symfony application’s Webpack Encore build, automatically discovering and registering both first-party controllers under assets/controllers/ and third-party controllers shipped by Symfony UX packages. It reads a controllers.json manifest — updated automatically by Symfony Flex whenever a UX package is installed — so adding a new UX component to a project requires no manual JavaScript wiring.

It exists specifically to remove Webpack boilerplate from the Symfony + Stimulus workflow: startStimulusApp() plus a lazy-controller loader handle require-context globbing, code-splitting, and registration in one call, which is the backbone of the entire Symfony UX ecosystem (Turbo, LiveComponent, and dozens of UX packages all depend on this bridge being present).

What You Get

• startStimulusApp() helper that bootstraps a Stimulus Application and registers all discovered controllers in one call
• A lazy-controller webpack loader (lazy-controller-loader.js) that code-splits controllers so they load only when needed
• Automatic reading of assets/controllers.json, which Symfony Flex rewrites whenever a Symfony UX package is installed or removed
• An enableStimulusBridge() Webpack Encore plugin entry point that hooks the bridge into an existing Encore build
• Support for both project-local controllers (assets/controllers/*_controller.js) and third-party controllers pulled from node_modules

Common Use Cases

• Bootstrapping Stimulus in a Symfony project that uses Webpack Encore, without hand-writing controller registration code
• Consuming Symfony UX packages (Turbo, LiveComponent, Chart.js bridge, etc.) that ship their own Stimulus controllers via controllers.json
• Splitting large controller sets into lazy-loaded chunks so unused controllers aren’t shipped to every page
• Migrating a legacy Symfony app that used plain jQuery/vanilla JS toward a lightweight, HTML-driven Stimulus architecture

Under The Hood

Architecture - The package is a small Webpack-era integration layer: startStimulusApp() in the main entry point takes a require.context result, instantiates a Stimulus Application, and registers each matched module as a controller by deriving its name from the file path. lazy-controller-loader.js is a custom Webpack loader that rewrites controller imports into dynamic import() calls so Webpack can code-split them, and enableStimulusBridge() is a thin Encore API hook that registers this loader and points it at the project’s controllers.json.

Tech Stack - Written in TypeScript, compiled to CommonJS for Webpack consumption, with peer dependencies on @hotwired/stimulus and webpack/webpack-encore; it has no runtime framework dependency beyond Stimulus itself.

Code Quality - The repository is intentionally minimal (a handful of source files plus TypeScript types), reflecting its role as glue code rather than an application framework; most behavioral correctness is exercised indirectly through the broader symfony/ux monorepo’s integration tests rather than dedicated unit tests in this repo.

API Design - The public surface is two functions (startStimulusApp, enableStimulusBridge) plus a webpack loader string, keeping integration to a few lines of webpack.config.js and assets/app.js; the tradeoff is that it is tightly coupled to Webpack Encore’s specific require.context conventions rather than being bundler-agnostic.