Document about alternative JS assets installation with npm packages

[Kocal]

Q	A
Bug fix?	no
New feature?	no
Issues	Fix #2575
License	MIT

Follow #2616

[Kocal]

There is no assets for symfony/ux-map, so let's remove this confusing part.

[javiereguiluz]

Teh way I see this is that we now have 3 different ways of installing this:

(1) PHP-based and uses AssetMapper

.. code-block:: terminal

    $ composer require symfony/ux-cropperjs

(2) PHP-based and uses WebpackEncore

.. code-block:: terminal

    $ composer require symfony/ux-cropperjs
    $ npm install --force
    $ npm run watch

(3) JavaScript-based

.. code-block:: terminal

    $ npm add @symfony/ux-cropperjs package

---

My questions:

• Is (3) totally equivalent to (1) and (2)
• If not, in which scenarios would someone use (3) vs (1) or (2)?

Based on the answers to these questions, let's think about the best possible way of showing this information. Thanks.

[Kocal]

(3) alone is not possible, each UX packages on npm (e.g.: https://www.npmjs.com/package/@symfony/ux-chartjs, https://www.npmjs.com/package/@symfony/ux-translator, ...) mention that the npm package must also install the php package.

See #2575 an #691 for more information, but to resume, having standalone JavaScript packages would allow users to install their JavaScript dependencies without needing PHP/Composer, which can be pretty useful in a CI (building Docker images, deploying an app, running JS tests, ...).

---

I would adapt your examples like this:

(1) PHP-based and uses AssetMapper

$ composer require symfony/ux-cropperjs

(2) PHP-based and uses WebpackEncore

$ composer require symfony/ux-cropperjs
$ # if user prefers to keep things separated: npm add -D @symfony/ux-cropperjs  
$ npm install --force
$ npm run watch

---

What do you think about that?

Based on the answers to these questions, let's think about the best possible way of showing this information. Thanks.

This is exactly why I added you as a reviewer 🤗

[javiereguiluz]

Thanks for the insights. I would expand each installation section as follows:

Installation
------------

.. caution::

    Before you start, make sure you have `StimulusBundle configured in your app`_.

Run the following command to install this package:

.. code-block:: terminal

    $ composer require symfony/ux-cropperjs

If your Symfony application uses `AssetMapper`_, you don't have to do anything else
and can move on to the next section.

If your Symfony application uses `Webpack Encore`_, run the following commands
to install the assets and restart Encore:

.. code-block:: terminal

    $ npm install --force
    $ npm run watch

.. tip::

    The assets of this package are also provided as the standalone `@symfony/ux-cropperjs`_
    JavaScript package. This is useful, for example, on continuous integration servers
    to build Docker images, run JavaScript tests, etc. without using PHP/Composer.

Usage
-----

[...]

.. _`AssetMapper`: https://symfony.com/doc/current/frontend/asset_mapper.html
.. _`Webpack Encore`: https://symfony.com/doc/current/frontend/encore/index.html

Although docs should be concise, I think it's fine to be a bit verbose/detailed in the Install section because any error here is very frustrating for readers.

I'd mention the scenarios where the JS package is useful. Experts won't need it, but the rest of folks would need this to decide if this is something for them or not.

---

I have a pending question. In the original text, we say things like:

Install the bundle using Composer and Symfony Flex:

What happens if the reader doesn't have Flex installed? Which steps should be done manually? Thanks

[Kocal]

I really like your suggestion, thanks Javier!

---

Install the bundle using Composer and Symfony Flex:

What happens if the reader doesn't have Flex installed? Which steps should be done manually? Thanks

If Flex is not installed, then the reader must do (unknown) operations manually:

1. Add the bundle in bundles.php
2. Do what the recipe does (e.g. with https://github.com/symfony/recipes/blob/main/symfony/ux-vue/2.9/manifest.json (add some lines, copy files, ...)
3. Modify its package.json and add the dependency file:vendor/symfony/ux-<pkg>/assets
4. and maybe more..

Which is far from being ideal.