[Frontend] Create a UX bundle: add requirements for Asset Mapper

Author: jmsche

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');
+        }
+    }