Add docs about creating UX bundles

Author: jmsche

bundles/best_practices.rst

@@ -546,6 +546,78 @@ Beware that templates use a simplified version of the logical path shown above.
 For example, an ``index.html.twig`` template located in the ``templates/Default/``
 directory of the AcmeBlogBundle, is referenced as ``@AcmeBlog/Default/index.html.twig``.
 
+Specifics for a UX bundle
+-------------------------
+
+Here are a few tricks to make your bundle install as a UX bundle.
+
+composer.json file
+~~~~~~~~~~~~~~~~~~
+
+Your ``composer.json`` file must have the ``symfony-ux`` keyword:
+
+.. code-block:: json
+
+    {
+        "keywords": ["symfony-ux"]
+    }
+
+Assets location
+~~~~~~~~~~~~~~~
+
+Your assets must be located in one of the following directories, with a ``package.json`` file so Flex can handle it
+during install/update:
+
+* ``/assets``
+* ``/Resources/assets``
+* ``/src/Resources/assets``
+
+package.json file
+~~~~~~~~~~~~~~~~~
+
+Your ``package.json`` file must contain a ``symfony`` config with controllers defined, and also add required packages
+to the ``peerDependencies``:
+
+.. code-block:: json
+
+    {
+        "name": "@acme/feature",
+        "symfony": {
+            "controllers": {
+                "slug": {
+                    "main": "dist/controller.js",
+                    "webpackMode": "eager",
+                    "fetch": "eager",
+                    "enabled": true,
+                    "autoimport": {
+                        "dist/bootstrap4-theme.css": false,
+                        "dist/bootstrap5-theme.css": true
+                    }
+                }
+            }
+        },
+        "peerDependencies": {
+            "@hotwired/stimulus": "^3.0.0",
+            "slugify": "^1.6.5"
+        }
+    }
+
+In this case, the file located at ``[assets directory]/dist/controller.js`` will be exposed.
+
+If the bundle is named ``acme/feature``, the base key for the controller will be ``acme--feature--slug``: it's composed
+of the bundle name and the controller name defined in the ``package.json`` file.
+
+To use it in a template (eg. one defined in your bundle) you can use it like this:
+
+.. code-block:: twig
+
+    <div
+        data-controller="acme--feature--slug"
+        data-acme--feature--slug-modal-value="my-value"
+    >
+        ...
+    </div>
+
 Learn more
 ----------