Document about alternative JS assets installation with npm packages

Kocal · Kocal · commit 7b7a9d3b3537 · 2025-03-09T22:10:04.000+01:00
diff --git a/assets/README.md b/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/ux-lazy-image@2.23.0
+```
 
 ## Resources
 
diff --git a/doc/index.rst b/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
