diff --git a/frontend/create_ux_bundle.rst b/frontend/create_ux_bundle.rst new file mode 100644 index 00000000000..1a93225b5ae --- /dev/null +++ b/frontend/create_ux_bundle.rst @@ -0,0 +1,139 @@ +.. index:: + single: Create a UX bundle + +Create a UX bundle +================== + +.. tip:: + + Before reading this, you may want to have a look at + :doc:`Best Practices for Reusable Bundles `. + +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`` (recommended) +* ``/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", + "version": "1.0.0", + "symfony": { + "controllers": { + "slug": { + "main": "dist/controller.js", + "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. + +.. tip:: + + You can either write raw JS in this ``dist/controller.js`` file, or you can e.g. write your controller with + TypeScript and transpile it to JavaScript. + + Here is an example to do so: + + 1. Add the following to your ``package.json`` file: + + .. code-block:: json + + { + "scripts": { + "build": "babel src --extensions .ts -d dist" + }, + "devDependencies": { + "@babel/cli": "^7.20.7", + "@babel/core": "^7.20.12", + "@babel/plugin-proposal-class-properties": "^7.18.6", + "@babel/preset-env": "^7.20.2", + "@babel/preset-typescript": "^7.18.6", + "@hotwired/stimulus": "^3.2.1", + "typescript": "^4.9.5" + } + } + + 2. Run either ``npm install`` or ``yarn install`` to install the new dependencies. + + 3. Write your Stimulus controller with TypeScript in ``src/controller.ts``. + + 4. 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: + +.. code-block:: html+twig + +