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

src/LiveComponent/assets/README.md

@@ -1,10 +1,18 @@
 # @symfony/ux-live-component
 
-Live Component: bring server-side re-rendering & model binding to any element.
+JavaScript assets of the [symfony/ux-live-component](https://packagist.org/packages/symfony/ux-live-component) PHP package.
 
-**ℹ️ Direct installation of this package is for advanced users only.** We strongly recommend installing it through the PHP package [symfony/ux-live-component](https://packagist.org/packages/symfony/ux-live-component) 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-live-component](https://packagist.org/packages/symfony/ux-live-component) 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-live-component](https://packagist.org/packages/symfony/ux-live-component) 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-live-component](https://packagist.org/packages/symfony/ux-live-component) PHP package version:
+```shell
+composer require symfony/ux-live-component:2.23.0
+npm add @symfony/[email protected]
+```
 
 ## Resources
 

src/LiveComponent/doc/index.rst

@@ -83,6 +83,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-live-component npm package`_
+
 If your project is localized in different languages (either via the `locale route parameter`_
 or by `setting the locale in the request`_) add the ``{_locale}`` attribute to
 the UX Live Components route definition to keep the locale between re-renders:
@@ -3800,7 +3804,7 @@ uses Symfony's test client to render and make requests to your components::
             // authenticate a user ($user is instance of UserInterface)
             $testComponent->actingAs($user);
 
-            // set the '_locale' route parameter (if the component route is localized)  
+            // set the '_locale' route parameter (if the component route is localized)
             $testComponent->setRouteLocale('fr');
 
             // customize the test client
@@ -3902,3 +3906,4 @@ promise. However, any internal implementation in the JavaScript files
 .. _`locale route parameter`: https://symfony.com/doc/current/translation.html#the-locale-and-the-url
 .. _`setting the locale in the request`: https://symfony.com/doc/current/translation.html#translation-locale
 .. _`Stimulus action parameter`: https://stimulus.hotwired.dev/reference/actions#action-parameters
+.. _`@symfony/ux-live-component npm package`: https://www.npmjs.com/package/@symfony/ux-live-component

src/Map/assets/README.md

@@ -1,6 +1,8 @@
 # @symfony/ux-map
 
-Easily embed interactive maps in your Symfony application.
+JavaScript assets of the [symfony/ux-map](https://packagist.org/packages/symfony/ux-map) PHP package.
+
+This package is private and is not intended to be published on npm or installed.
 
 ## Resources
 

src/Map/doc/index.rst

@@ -16,14 +16,6 @@ Install the bundle using Composer and Symfony Flex:
 
     $ composer require symfony/ux-map
 
-If you're using WebpackEncore, install your assets and restart Encore (not
-needed if you're using AssetMapper):
-
-.. code-block:: terminal
-
-    $ npm install --force
-    $ npm run watch
-
 Configuration
 -------------
 
@@ -140,25 +132,25 @@ Remove elements from Map
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 It is possible to remove elements like ``Marker``, ``Polygon`` and ``Polyline`` instances by using ``Map::remove*()`` methods::
-    
+
     // Add elements
     $map->addMarker($marker = new Marker(/* ... */));
     $map->addPolygon($polygon = new Polygon(/* ... */));
     $map->addPolyline($polyline = new Polyline(/* ... */));
-    
+
     // And later, remove those elements
     $map->removeMarker($marker);
     $map->removePolygon($polygon);
     $map->removePolyline($polyline);
-    
+
 If unfortunately you were unable to store an element instance, you can still remove them by passing the identifier string::
- 
+
     $map = new Map(/* ... */);
     // Add elements
     $map->addMarker(new Marker(id: 'my-marker', /* ... */));
     $map->addPolygon(new Polygon(id: 'my-polygon', /* ... */));
     $map->addPolyline(new Polyline(id: 'my-marker', /* ... */));
-    
+
     // And later, remove those elements
     $map->removeMarker('my-marker');
     $map->removePolygon('my-polygon');

src/Map/src/Bridge/Google/README.md

@@ -2,6 +2,25 @@
 
 [Google Maps](https://developers.google.com/maps/documentation/javascript/overview) integration for Symfony UX Map.
 
+## Installation
+
+Install the bridge using Composer and Symfony Flex:
+
+```shell
+composer require symfony/ux-google-map
+```
+
+If you're using WebpackEncore, install your assets and restart Encore (not
+needed if you're using AssetMapper):
+
+```shell
+npm install --force
+npm run watch
+```
+
+> [!NOTE]
+> Alternatively, [@symfony/ux-google-map package](https://www.npmjs.com/package/@symfony/ux-google-map) can be used to install the JavaScript assets without requiring PHP.
+
 ## DSN example
 
 ```dotenv