README

This bundle adds integration between MultiAssetMapperBundle and Stimulus, allowing you to manage a different set of Stimulus controllers per asset collection.

This bundle is based on StimulusBundle by Symfony, licensed under MIT.

Why use this bundle?

When using MultiAssetMapperBundle, you can have multiple asset collections in your Symfony project. Each collection can have its own set of Stimulus controllers. This bundle allows you to manage those controllers separately.

Examples of common asset collections that demand different sets of Stimulus controllers:

admin, backend: for the admin area of your application
frontend, public: for the public-facing website
mobile, desktop: for different device-specific assets
marketing, blog: for marketing or blog sections of your application
legacy, modern: for legacy and modern versions of your application
user, guest: for user-specific and guest-specific assets
theme1, theme2: for different themes or skins of your application

Installation

Add the bundle to your Symfony project

You can install this bundle using Composer:

composer require prr/multi-stimulus-bundle

Configure the bundle

Create config/packages/multi_stimulus.yaml listing the asset collections you want to manage. In the following example, we are managing two asset collections: admin and frontend.

multi_stimulus:
    # The list of asset collections that will use Stimulus controllers
    collections:
        - admin
        - frontend

Now, setup to load the controllers for each asset collection running the following command:

php bin/console multi:stimulus:setup

Check if the bundle is aware of the new configuration:

php bin/console debug:config multi_stimulus

Configure Multi Asset Mapper to load the Stimulus controllers loader

Asset Mapper needs to know where to find the package @prr/multi-stimulus-bundle in order to load the Stimulus controllers loader. You can do this by changing the configuration in your config/packages/multi_asset_mapper.yaml file. In the following example, we are configuring the admin asset collection to be aware of @prr/multi-stimulus-bundle package:

multi_asset_mapper:
  # The list of asset collections to manage
  collections:
    admin:
      paths:
        vendor/prr/multi-stimulus-bundle/assets/dist/: '@prr/multi-stimulus-bundle'
        asset-collections/admin/: ''
      excluded_patterns:
        - '*.d.ts'
        - '*/controllers.json'
    frontend: ~

You also need to configure the corresponding importmap.php to use the controllers loader whenever the bare import @prr/multi-stimulus-bundle is used.

<?php
return [
    'main' => [
        'path' => './asset-collections/admin/main.js',
        'entrypoint' => true,
    ],
    '@hotwired/stimulus' => [
        'version' => '3.2.2',
    ],
    '@prr/multi-stimulus-bundle' => [
        'path' => '@prr/multi-stimulus-bundle/loader.js',
    ],
    // ... other imports
];

Now create a page that uses a Stimulus controller from the admin asset collection. It should work as expected.

Usage

Including a Stimulus controller outside your controllers directory

First, Asset Mapper must be configured to include the directory where the controller is located. For example, if you have a controller in ../../asset-collections/shared/controllers/my-shared-controller.js, you need to configure Multi Package Asset Mapper like this:

multi_asset_mapper:
    packages:
        admin_v1:
            # The paths to make available to the asset mapper.
            paths:
                asset-packages/shared/: '@shared'
                asset-packages/admin_v1/: ''
            vendor_dir: '%kernel.project_dir%/asset-packages/admin_v1/vendor'
            public_prefix: /asset-packages/admin_v1/
            importmap_path: '%kernel.project_dir%/asset-packages/admin_v1/importmap.php'

Second, import the controller in your bootstrap-stimulus.js file:

import { startStimulusApp } from '@prr/multi-stimulus-bundle';
import { eagerControllers, lazyControllers, isApplicationDebug } from "./autoload-controllers.js";
import MySharedController from '../shared/controllers/my-shared-controller.js';

const app = startStimulusApp(eagerControllers, lazyControllers, isApplicationDebug);
// register any custom, 3rd party controllers here
app.register('my-shared', MySharedController);

prr / multi-stimulus-bundle

Maintainers

Package info

Statistics

Security