[Docs] More explicit usage examples

[maelanleborgne]

We had a few issues opened by people who were confused on how to use the bundle.
The example in the doc was not using the standard "entrypoint / importmap" method from the AssetMapper component, and there was no mention of the ability to import TypeScript files from other JS/TS files.
The doc should definitely be more explicit on what the bundle can do and how to do it.
This is an attempt to clear things up, but I'm no documentation expert so any input would be appreciated :)

[javiereguiluz]

In addition to the new defaults to ... text added above, I'd keep the original config example too to make it more clear:

.. code-block:: yaml

    # config/packages/asset_mapper.yaml
    sensiolabs_typescript:
        source_dir: ['%kernel.project_dir%/assets/typescript']

[smnandre]

Not sure if this already works ... but if "not"

I think you should allow a path or an array of paths there... (we did it in the sassbundle some time ago if you want to have a look and avoid time on doc :) )

Little thing, but still a DX improvement some people enjoy :)

(well... me at least 😅 )

[javiereguiluz]

I'd add a short example of how to use each of these three ways.

This way you can add short but useful explanations if needed. For example:

By including a raw file in your templates ``<script type="module" src="{{ asset('app.ts') }}"></script>``

Could be something similar to https://symfony.com/doc/current/frontend/asset_mapper.html#mapping-and-referencing-assets

Including a Raw TypeScript File in the Template
-----------------------------------------------

Use the `asset() Twig function`_ to link to TypeScript files from any Twig
template:

.. code-block:: twig

    <script type="module" src="{{ asset('app.ts') }}"></script>

The path - ``app.ts`` - is relative to the directory configured in the
``sensiolabs_typescript.source_dir`` option. This is known as the logical path
to your asset.

If you look at the HTML in your page, the actual URL will be something like:
``/assets/app-3c16d9220694c0e56d8648f25e6035e9.ts``. If you change the file,
the version part of the URL will also change automatically.

.. _`asset() Twig function`: https://symfony.com/doc/current/reference/twig_reference.html#asset

[smnandre]

I would not recommand this

[maelanleborgne]

I wouldn't either, but if the application entrypoint is a typescript file ("app.ts") or if there is a real need for another entrypoint (since it's documented in the AssetMapper documentation) I think we should mention it.
But maybe we could change the order or the options, or mention that the best practice is to have a single entrypoint and import files from there, or use stimulus controllers for context-specific files ?

[smnandre]

Is this realtime ? Or deployed once ?

[maelanleborgne]

It's compiled once or using the watch option, no real-time compiling at the moment (and not planned).

[smnandre]

I meant the "Finally, when the content is requested, the bundle swaps the contents of that file ...."

Is this done "when the content is requested" or only once on asset mapper deploy ?

[maelanleborgne]

This works leveraging AssetMapper : it's swapped when running asset-map-compile(you'll only have js files in the public/assets directory) or on the fly in dev mode.

[smnandre]

I really need to improve my communication... :))

What i wanted to point out is, the sentence "when the content is requested, the bundle swaps the contents " could be missleading for the user, and maybe should be replaced, as you just said, by something like

"In dev, ..... bla bla bla in real time. In prod, during deployment ...." :)