Document about alternative JS assets installation with npm packages

Author: Kocal

src/Autocomplete/assets/README.md

@@ -1,10 +1,18 @@
 # @symfony/ux-autocomplete
 
-Javascript-powered auto-completion functionality for your Symfony forms!
+JavaScript assets of the [symfony/ux-autocomplete](https://packagist.org/packages/symfony/ux-autocomplete) PHP package.
 
-**ℹ️ Direct installation of this package is for advanced users only.** We strongly recommend installing it through the PHP package [symfony/ux-autocomplete](https://packagist.org/packages/symfony/ux-autocomplete) in a Symfony application with Flex enabled.
+## Installation
 
-If you still want to install this package directly, **make sure its version exactly matches [symfony/ux-autocomplete](https://packagist.org/packages/symfony/ux-autocomplete) PHP package version.**
+This npm package is **reserved for advanced users** who want to decouple their JavaScript dependencies from their PHP dependencies (e.g., when building Docker images, running JavaScript-only pipelines, etc.).
+
+We **strongly recommend not installing this package directly**, but instead  install the PHP package [symfony/ux-autocomplete](https://packagist.org/packages/symfony/ux-autocomplete) in your Symfony application with [Flex](https://github.com/symfony/flex) enabled.
+
+If you still want to install this package directly, please make sure its version exactly matches [symfony/ux-autocomplete](https://packagist.org/packages/symfony/ux-autocomplete) PHP package version:
+```shell
+composer require symfony/ux-autocomplete:2.23.0
+npm add @symfony/[email protected]
+```
 
 ## Resources
 

src/Autocomplete/doc/index.rst

@@ -30,6 +30,10 @@ needed if you're using AssetMapper):
     $ npm install --force
     $ npm run watch
 
+.. note::
+
+    For more complex installation scenarios, you can install the JavaScript assets through the `@symfony/ux-autocomplete npm package`_
+
 Usage in a Form (without Ajax)
 ------------------------------
 
@@ -288,7 +292,7 @@ Passing Extra Options to the Ajax-powered Autocomplete
 
 Autocomplete field options are **not preserved** when the field is rendered
 on an Ajax call. So, features like exclude some options based on the current
-form data are not possible by default. 
+form data are not possible by default.
 
 To partially avoid this limitation, the ``extra_options`` option was added.
 
@@ -299,7 +303,7 @@ To partially avoid this limitation, the ``extra_options`` option was added.
     can be passed as extra options.
 
 Considering the following example, when the form type is rendered for the first
-time, it will use the ``query_builder`` defined while adding a ``food`` field 
+time, it will use the ``query_builder`` defined while adding a ``food`` field
 to the ``FoodForm``. However, when the Ajax is used to fetch the results, on
 the consequent renders, the default ``query_builder`` will be used::
 
@@ -324,8 +328,8 @@ the consequent renders, the default ``query_builder`` will be used::
         }
     }
 
-If some food can be consisted of other foods, we might want to exclude the 
-"root" food from the list of available foods. To achieve this, we can remove 
+If some food can be consisted of other foods, we might want to exclude the
+"root" food from the list of available foods. To achieve this, we can remove
 the ``query_builder`` option from the above example and pass the ``excluded_foods``
 extra option to the ``FoodAutocompleteField``::
 
@@ -600,13 +604,13 @@ Passing Extra Options to the Autocompleter
 
     The ability to pass extra options was added in Autocomplete 2.14.
 
-If you need to pass extra options to the autocompleter, you can do so by 
-implementing the ``\Symfony\UX\Autocomplete\OptionsAwareEntityAutocompleterInterface`` 
+If you need to pass extra options to the autocompleter, you can do so by
+implementing the ``\Symfony\UX\Autocomplete\OptionsAwareEntityAutocompleterInterface``
 interface.
 
 .. tip::
 
-    If you want to know **why** you might need to use the ``extra_options`` 
+    If you want to know **why** you might need to use the ``extra_options``
     feature, see :ref:`passing-extra-options-to-the-ajax-powered-autocomplete`.
 
 .. code-block:: diff
@@ -757,3 +761,4 @@ the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html
 .. _`Tom Select Render Templates`: https://tom-select.js.org/docs/#render-templates
 .. _`Tom Select Option Group`: https://tom-select.js.org/examples/optgroups/
 .. _`Symfony Form`: https://symfony.com/doc/current/forms.html
+.. _`@symfony/ux-autocomplete npm package`: https://www.npmjs.com/package/@symfony/ux-autocomplete

src/Chartjs/assets/README.md

@@ -1,10 +1,18 @@
 # @symfony/ux-chartjs
 
-Chart.js integration for Symfony.
+JavaScript assets of the [symfony/ux-chartjs](https://packagist.org/packages/symfony/ux-chartjs) PHP package.
 
-**ℹ️ Direct installation of this package is for advanced users only.** We strongly recommend installing it through the PHP package [symfony/ux-chartjs](https://packagist.org/packages/symfony/ux-chartjs) in a Symfony application with Flex enabled.
+## Installation
 
-If you still want to install this package directly, **make sure its version exactly matches [symfony/ux-chartjs](https://packagist.org/packages/symfony/ux-chartjs) PHP package version.**
+This npm package is **reserved for advanced users** who want to decouple their JavaScript dependencies from their PHP dependencies (e.g., when building Docker images, running JavaScript-only pipelines, etc.).
+
+We **strongly recommend not installing this package directly**, but instead  install the PHP package [symfony/ux-chartjs](https://packagist.org/packages/symfony/ux-chartjs) in your Symfony application with [Flex](https://github.com/symfony/flex) enabled.
+
+If you still want to install this package directly, please make sure its version exactly matches [symfony/ux-chartjs](https://packagist.org/packages/symfony/ux-chartjs) PHP package version:
+```shell
+composer require symfony/ux-chartjs:2.23.0
+npm add @symfony/[email protected]
+```
 
 ## Resources
 

src/Chartjs/doc/index.rst

@@ -22,6 +22,10 @@ needed if you're using AssetMapper):
     $ npm install --force
     $ npm run watch
 
+.. note::
+
+    For more complex installation scenarios, you can install the JavaScript assets through the `@symfony/ux-chartjs npm package`_
+
 Usage
 -----
 
@@ -253,3 +257,4 @@ the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html
 .. _`zoom plugin documentation`: https://www.chartjs.org/chartjs-plugin-zoom/latest/guide/integration.html
 .. _`register Chart.js plugins globally`: https://www.chartjs.org/docs/latest/developers/plugins.html
 .. _`Tooltip positioner`: https://www.chartjs.org/docs/latest/samples/tooltip/position.html
+.. _`@symfony/ux-chartjs npm package`: https://www.npmjs.com/package/@symfony/ux-chartjs

src/Cropperjs/assets/README.md

@@ -1,10 +1,18 @@
 # @symfony/ux-cropperjs
 
-Cropper.js integration for Symfony.
+JavaScript assets of the [symfony/ux-cropperjs](https://packagist.org/packages/symfony/ux-cropperjs) PHP package.
 
-**ℹ️ Direct installation of this package is for advanced users only.** We strongly recommend installing it through the PHP package [symfony/ux-cropperjs](https://packagist.org/packages/symfony/ux-cropperjs) in a Symfony application with Flex enabled.
+## Installation
 
-If you still want to install this package directly, **make sure its version exactly matches [symfony/ux-cropperjs](https://packagist.org/packages/symfony/ux-cropperjs) PHP package version.**
+This npm package is **reserved for advanced users** who want to decouple their JavaScript dependencies from their PHP dependencies (e.g., when building Docker images, running JavaScript-only pipelines, etc.).
+
+We **strongly recommend not installing this package directly**, but instead  install the PHP package [symfony/ux-cropperjs](https://packagist.org/packages/symfony/ux-cropperjs) in your Symfony application with [Flex](https://github.com/symfony/flex) enabled.
+
+If you still want to install this package directly, please make sure its version exactly matches [symfony/ux-cropperjs](https://packagist.org/packages/symfony/ux-cropperjs) PHP package version:
+```shell
+composer require symfony/ux-cropperjs:2.23.0
+npm add @symfony/[email protected]
+```
 
 ## Resources
 

src/Cropperjs/doc/index.rst

@@ -26,6 +26,10 @@ needed if you're using AssetMapper):
     $ npm install --force
     $ npm run watch
 
+.. note::
+
+    For more complex installation scenarios, you can install the JavaScript assets through the `@symfony/ux-cropperjs npm package`_
+
 Usage
 -----
 
@@ -149,3 +153,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
 .. _`the Symfony UX initiative`: https://ux.symfony.com/
 .. _`the Cropper.js options`: https://github.com/fengyuanchen/cropperjs/blob/main/README.md#options
 .. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
+.. _`@symfony/ux-cropperjs npm package`: https://www.npmjs.com/package/@symfony/ux-cropperjs

src/Dropzone/assets/README.md

@@ -1,10 +1,18 @@
 # @symfony/ux-dropzone
 
-File input dropzones for Symfony Forms.
+JavaScript assets of the [symfony/ux-dropzone](https://packagist.org/packages/symfony/ux-dropzone) PHP package.
 
-**ℹ️ Direct installation of this package is for advanced users only.** We strongly recommend installing it through the PHP package [symfony/ux-dropzone](https://packagist.org/packages/symfony/ux-dropzone) in a Symfony application with Flex enabled.
+## Installation
 
-If you still want to install this package directly, **make sure its version exactly matches [symfony/ux-dropzone](https://packagist.org/packages/symfony/ux-dropzone) PHP package version.**
+This npm package is **reserved for advanced users** who want to decouple their JavaScript dependencies from their PHP dependencies (e.g., when building Docker images, running JavaScript-only pipelines, etc.).
+
+We **strongly recommend not installing this package directly**, but instead  install the PHP package [symfony/ux-dropzone](https://packagist.org/packages/symfony/ux-dropzone) in your Symfony application with [Flex](https://github.com/symfony/flex) enabled.
+
+If you still want to install this package directly, please make sure its version exactly matches [symfony/ux-dropzone](https://packagist.org/packages/symfony/ux-dropzone) PHP package version:
+```shell
+composer require symfony/ux-dropzone:2.23.0
+npm add @symfony/[email protected]
+```
 
 ## Resources
 

src/Dropzone/doc/index.rst

@@ -28,6 +28,10 @@ needed if you're using AssetMapper):
     $ npm install --force
     $ npm run watch
 
+.. note::
+
+    For more complex installation scenarios, you can install the JavaScript assets through the `@symfony/ux-dropzone npm package`_
+
 Usage
 -----
 
@@ -155,3 +159,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
 
 .. _`the Symfony UX initiative`: https://ux.symfony.com/
 .. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
+.. _`@symfony/ux-dropzone npm package`: https://www.npmjs.com/package/@symfony/ux-dropzone

src/LazyImage/assets/README.md

@@ -1,10 +1,18 @@
 # @symfony/ux-lazy-image
 
-Lazy image loader and utilities for Symfony.
+JavaScript assets of the [symfony/ux-lazy-image](https://packagist.org/packages/symfony/ux-lazy-image) PHP package.
 
-**ℹ️ Direct installation of this package is for advanced users only.** We strongly recommend installing it through the PHP package [symfony/ux-lazy-image](https://packagist.org/packages/symfony/ux-lazy-image) in a Symfony application with Flex enabled.
+## Installation
 
-If you still want to install this package directly, **make sure its version exactly matches [symfony/ux-lazy-image](https://packagist.org/packages/symfony/ux-lazy-image) PHP package version.**
+This npm package is **reserved for advanced users** who want to decouple their JavaScript dependencies from their PHP dependencies (e.g., when building Docker images, running JavaScript-only pipelines, etc.).
+
+We **strongly recommend not installing this package directly**, but instead  install the PHP package [symfony/ux-lazy-image](https://packagist.org/packages/symfony/ux-lazy-image) in your Symfony application with [Flex](https://github.com/symfony/flex) enabled.
+
+If you still want to install this package directly, please make sure its version exactly matches [symfony/ux-lazy-image](https://packagist.org/packages/symfony/ux-lazy-image) PHP package version:
+```shell
+composer require symfony/ux-lazy-image:2.23.0
+npm add @symfony/[email protected]
+```
 
 ## Resources
 

src/LazyImage/doc/index.rst

@@ -36,6 +36,10 @@ needed if you're using AssetMapper):
     $ npm install --force
     $ npm run watch
 
+.. note::
+
+    For more complex installation scenarios, you can install the JavaScript assets through the `@symfony/ux-lazy-image npm package`_
+
 Usage
 -----
 
@@ -216,7 +220,7 @@ on the page and should be less than 2.5 seconds. It's part of the `Core Web Vita
 and is used by Google to evaluate the user experience of a website, impacting
 the Search ranking.
 
-Using the Symfony UX LazyImage for your LCP image can be a good idea at first, 
+Using the Symfony UX LazyImage for your LCP image can be a good idea at first,
 but in reality, it will lower the LCP score because:
 
 - `The progressive loading (through blurhash) is not taken into account in the LCP calculation`_;
@@ -239,7 +243,7 @@ A solution is to not use the Stimulus controller for the LCP image but to use
         width="200"
         height="150"
     />
-    
+
 This way, the browser will display the BlurHash image as soon as possible, and
 will load the high-definition image at the same time, without waiting for the
 Stimulus controller to be loaded.
@@ -262,3 +266,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
 .. _`Core Web Vitals`: https://web.dev/vitals/
 .. _`The progressive loading (through blurhash) is not taken into account in the LCP calculation`: https://github.com/w3c/largest-contentful-paint/issues/71_
 .. _`didn't preload the image`: https://symfony.com/doc/current/web_link.html
+.. _`@symfony/ux-lazy-image npm package`: https://www.npmjs.com/package/@symfony/ux-lazy-image