diff --git a/frontend/create_ux_bundle.rst b/frontend/create_ux_bundle.rst index 12002d10356..7a32d4b9cd6 100644 --- a/frontend/create_ux_bundle.rst +++ b/frontend/create_ux_bundle.rst @@ -33,7 +33,8 @@ package.json file ----------------- Your ``package.json`` file must contain a ``symfony`` config with controllers defined, and also add required packages -to the ``peerDependencies``: +to the ``peerDependencies`` and ``importmap`` (the list of packages in ``importmap`` should be the same as the ones +in ``peerDependencies``): .. code-block:: json @@ -51,6 +52,10 @@ to the ``peerDependencies``: "dist/bootstrap5-theme.css": true } } + }, + "importmap": { + "@hotwired/stimulus": "^3.0.0", + "slugify": "^1.6.5" } }, "peerDependencies": { @@ -87,11 +92,28 @@ In this case, the file located at ``[assets directory]/dist/controller.js`` will } } - 2. Run either ``npm install`` or ``yarn install`` to install the new dependencies. + 2. Add the following to your ``babel.config.js`` file (should be located next to your ``package.json`` file): - 3. Write your Stimulus controller with TypeScript in ``src/controller.ts``. + .. code-block:: javascript - 4. Run ``npm run build`` or ``yarn run build`` to transpile your TypeScript controller into JavaScript. + module.exports = { + presets: [ + ['@babel/preset-env', { + "loose": true, + "modules": false + }], + ['@babel/preset-typescript', { allowDeclareFields: true }] + ], + assumptions: { + superIsCallableConstructor: false, + }, + }; + + 3. Run either ``npm install`` or ``yarn install`` to install the new dependencies. + + 4. Write your Stimulus controller with TypeScript in ``src/controller.ts``. + + 5. Run ``npm run build`` or ``yarn run build`` to transpile your TypeScript controller into JavaScript. To use your controller in a template (e.g. one defined in your bundle) you can use it like this: @@ -134,3 +156,49 @@ autoimport List of files to be imported with the controller. Useful e.g The value must be an object with files as keys, and a boolean as value for each file to set whether the file should be imported. ================== ==================================================================================================== + +Specifics for Asset Mapper +-------------------------- + +To make your bundle's assets work with Asset Mapper, you must add the ``importmap`` config like above in your +``package.json`` file, and prepend some configuration to the container:: + + namespace Acme\FeatureBundle; + + use Symfony\Component\AssetMapper\AssetMapperInterface; + use Symfony\Component\DependencyInjection\ContainerBuilder; + use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator; + use Symfony\Component\HttpKernel\Bundle\AbstractBundle; + + class AcmeFeatureBundle extends AbstractBundle + { + public function prependExtension(ContainerConfigurator $configurator, ContainerBuilder $container): void + { + if (!$this->isAssetMapperAvailable($container)) { + return; + } + + $container->prependExtensionConfig('framework', [ + 'asset_mapper' => [ + 'paths' => [ + __DIR__ . '/../assets/dist' => '@acme/feature-bundle', + ], + ], + ]); + } + + private function isAssetMapperAvailable(ContainerBuilder $container): bool + { + if (!interface_exists(AssetMapperInterface::class)) { + return false; + } + + // check that FrameworkBundle 6.3 or higher is installed + $bundlesMetadata = $container->getParameter('kernel.bundles_metadata'); + if (!isset($bundlesMetadata['FrameworkBundle'])) { + return false; + } + + return is_file($bundlesMetadata['FrameworkBundle']['path'] . '/Resources/config/asset_mapper.php'); + } + }