Skip to content

[Docs] More explicit usage examples #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[Docs] More explicit usage examples #44

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 6 additions & 20 deletions doc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,26 +21,12 @@ Usage
-----

Start by setting the ``sensiolabs_typescript.source_dir`` option to the list of
locations where your TypeScript files are located.
locations where your TypeScript files are located (defaults to ``[%kernel.project_dir%/assets]``).

For instance, if your TypeScript code lives in ``assets/typescript/`` directory,
with an ``assets/typescript/app.ts`` entrypoint file, set the option like this:

.. code-block:: yaml
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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']

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 😅 )


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

Then load your TypeScript files in your templates:

.. code-block:: html+twig

{# templates/base.html.twig #}

{% block javascripts %}
<script type="text/javascript" src="{{ asset('typescript/app.ts') }}"></script>
{% endblock %}
There are three ways to use your TypeScript files using this bundle:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

* By defining TypeScript files as **entrypoints** in ``importmap.php``, then using the `importmap() Twig function <https://symfony.com/doc/current/frontend/asset_mapper.html#how-does-the-importmap-work>`_.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would not recommand this

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ?

* By **importing** TypeScript files from your existing JavaScript files.
* By including a raw file in your templates ``<script type="module" src="{{ asset('app.ts') }}"></script>``.

Finally run this command:

Expand Down Expand Up @@ -81,7 +67,7 @@ The first time you run one of the TypeScript commands, the bundle will download
the correct SWC binary for your system into the ``var/`` directory.

When you run ``typescript:build``, that binary is used to compile TypeScript files
into a ``var/typescript/`` directory. Finally, when the contents of ``assets/typescript/app.ts``
into a ``var/typescript/`` directory. Finally, when the contents of ``assets/app.ts``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this realtime ? Or deployed once ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ...." :)

is requested, the bundle swaps the contents of that file with the contents of
the ``var/typescript/`` directory.

Expand Down
Loading