Vite AssetCollector for TYPO3
=============================
|Maintainability| |Test Coverage| |tests| |Total downloads| |TYPO3
versions| |Latest version|
Bundle your TYPO3 frontend assets with `vite `__, a
modern and flexible frontend tool. This TYPO3 extension provides a
future-proof integration for vite using TYPO3’s AssetCollector API. This
means that you can use vite’s hot reloading and hot module replacement
features (and many others) in your TYPO3 projects.
This extension is inspired by
`typo3-vite-demo `__ which
was created by `Florian Geierstanger `__.
Installation
------------
Vite AssetCollector can be installed with composer:
.. code:: sh
composer req praetorius/vite-asset-collector
vite can be installed with the frontend package manager of your choice:
.. code:: sh
npm install --save-dev vite vite-plugin-auto-origin
`vite-plugin-auto-origin `__\ *is
recommended as it simplifies configuration and daily usage of vite with
TYPO3.*
Getting Started
---------------
1. Vite Setup
~~~~~~~~~~~~~
To get things started, the extension provides a console command that
generates a ready-to-use ``vite.config.js`` file:
.. code:: sh
vendor/bin/typo3 vite:config --entry 'EXT:sitepackage/Resources/Private/Main.entry.js' --outputfile ./vite.config.js
The generated configuration makes sure that vite
- knows the location of your main JavaScript file, also known as
*entrypoint*
- generates a ``manifest.json`` file
- outputs assets to a publicly accessible directory
Note that the console command is only intended as a kickstarter for your
initial vite configuration file.
.. raw:: html
More Options
- You can define multiple ``--entry`` options.
- You can add ``--glob`` to enable pattern matching for your entrypoint
paths (`fast-glob `__
required).
- If you omit ``--outputfile``, the file content will be outputted
instead.
- Add ``--no-auto-origin`` if you don’t want to use
`vite-plugin-auto-origin `__.
Note that you need to specify ``VITE_DEV_ORIGIN`` manually then.
- ``--help`` shows all available options.
.. raw:: html
2. TYPO3 Setup
~~~~~~~~~~~~~~
Then you can use the included ViewHelper to embed your assets. If you
use the default configuration, you only need to specify your entrypoint.
**Layouts/Default.html**:
.. code:: xml
...
3. Start Developing
~~~~~~~~~~~~~~~~~~~
Development environments can be highly individual. However, if ddev is
your tool of choice for local development, a few steps can get you
started with a ready-to-use development environment with vite, composer
and TYPO3.
`Instructions for DDEV <./Documentation/DdevSetup.md>`__
Configuration
-------------
If you use the setup as described above, no configuration should be
necessary. However, you can customize almost everything to create your
individual development setup:
.. raw:: html
Adjust vite dev server
The extension has two configuration options to setup the vite dev
server. By default, both are set to ``auto``, which means:
- Dev server will only be used in ``Development`` context
- Dev server uri will be determined automatically for environments with
`vite-serve for DDEV `__
set up
You can adjust both options in your ``$TYPO3_CONF_VARS``, for example:
.. code:: php
// Setup vite dev server based on configuration in .env file
// TYPO3_VITE_DEV_SERVER='https://localhost:1234'
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['vite_asset_collector']['useDevServer'] = (bool) getenv('TYPO3_VITE_DEV_SERVER');
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['vite_asset_collector']['devServerUri'] = (string) getenv('TYPO3_VITE_DEV_SERVER');
.. raw:: html
.. raw:: html
Change location of default manifest.json
You can specify a default manifest file in the extension configuration.
By default, this is set to ``_assets/vite/.vite/manifest.json``, so it
will run out-of-the-box with vite 5 if you generated your vite
configuration with this extension. If you still use vite < 5, you should
to change this to ``_assets/vite/manifest.json``.
If you change the path here, please be aware that you may need to adjust
your the ``outDir`` in your ``vite.config.js`` as well:
.. code:: php
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['vite_asset_collector']['defaultManifest'] = 'EXT:sitepackage/Resources/Public/Vite/.vite/manifest.json';
If you use the ``vite.config.js`` provided by the extension:
.. code:: js
// Output path for generated assets
const VITE_OUTPUT_PATH = 'packages/sitepackage/Resources/Public/Vite/';
If you use your own ``vite.config.js``:
.. code:: js
export default defineConfig({
// ...
outDir: 'path/to/sitepackage/Resources/Public/Vite/',
})
.. raw:: html
ViewHelper Reference
--------------------
asset.vite ViteHelper
~~~~~~~~~~~~~~~~~~~~~
The ``asset.vite`` ViewHelper embeds all JavaScript and CSS belonging to
the specified vite ``entry`` using TYPO3’s AssetCollector API.
.. raw:: html
Arguments
- ``manifest`` (type: ``string``): Path to your manifest.json file. If
omitted, default manifest from extension configuration will be used
instead.
- ``entry`` (type: ``string``): Identifier of the desired vite
entrypoint; this is the value specified as ``input`` in the vite
configuration file. Can be omitted if manifest file exists and only
one entrypoint is present.
- ``devTagAttributes`` (type: ``array``): HTML attributes that should
be added to script tags that point to the vite dev server
- ``scriptTagAttributes`` (type: ``array``): HTML attributes that
should be added to script tags for built JavaScript assets
- ``cssTagAttributes`` (type: ``array``): HTML attributes that should
be added to css link tags for built CSS assets
- ``priority`` (type: ``bool``, default: ``false``): Include assets
before other assets in HTML
- ``useNonce`` (type: ``bool``, default: ``false``): Whether to use the
global nonce value
- ``addCss`` (type: ``bool``, default: ``true``): If set to ``false``,
CSS files associated with the entry point won’t be added to the asset
collector
.. raw:: html
.. raw:: html
Example
.. code:: xml
.. raw:: html
resource.vite ViteHelper
~~~~~~~~~~~~~~~~~~~~~~~~
The ``resource.vite`` ViewHelper extracts the uri to one specific asset
file from a vite manifest file.
.. raw:: html
Arguments
- ``manifest`` (type: ``string``): Path to your manifest.json file. If
omitted, default manifest from extension configuration will be used
instead.
- ``file`` (type: ``string``): Identifier of the desired asset file for
which a uri should be generated
.. raw:: html
.. raw:: html
Example
This can be used to preload certain assets in the HTML ```` tag:
.. code:: xml
.. raw:: html
Vite Assets in Yaml Files
-------------------------
Besides ViewHelpers, the extension includes a processor for Yaml files,
which allows you to use assets generated by vite in your configuration
files. This is especially useful for `custom RTE
presets `__:
.. code:: yaml
editor:
config:
contentsCss:
# Using the default manifest file
- "%vite('EXT:sitepackage/Resources/Private/Css/Rte.css')%"
# Using another manifest.json
- "%vite('EXT:sitepackage/Resources/Private/Css/Rte.css', 'path/to/manifest.json')%"
TYPO3 Icon API
--------------
The extension includes a custom ``SvgIconProvider`` for the `TYPO3 Icon
API `__,
which allows you to register SVG icon files generated by vite. This
works both in frontend and backend context.
To register a new icon, add the following to the
``Configuration/Icons.php`` file:
.. code:: php
return [
'site-logo' => [
'provider' => \Praetorius\ViteAssetCollector\IconProvider\SvgIconProvider::class,
'source' => 'assets/Image/Icon/typo3.svg',
'manifest' => 'path/to/manifest.json', // optional, defaults to defaultManifest
],
];
Then you can use the `core:icon
ViewHelper `__
to use the icon in your templates.
.. |Maintainability| image:: https://api.codeclimate.com/v1/badges/161b455fe0abc70be677/maintainability
:target: https://codeclimate.com/github/s2b/vite-asset-collector/maintainability
.. |Test Coverage| image:: https://api.codeclimate.com/v1/badges/161b455fe0abc70be677/test_coverage
:target: https://codeclimate.com/github/s2b/vite-asset-collector/test_coverage
.. |tests| image:: https://github.com/s2b/vite-asset-collector/actions/workflows/tests.yaml/badge.svg
:target: https://github.com/s2b/vite-asset-collector/actions/workflows/tests.yaml
.. |Total downloads| image:: https://typo3-badges.dev/badge/vite_assetcollector/downloads/shields.svg
:target: https://extensions.typo3.org/extension/vite_asset_collector
.. |TYPO3 versions| image:: https://typo3-badges.dev/badge/vite_assetcollector/typo3/shields.svg
:target: https://extensions.typo3.org/extension/vite_asset_collector
.. |Latest version| image:: https://typo3-badges.dev/badge/vite_assetcollector/version/shields.svg
:target: https://extensions.typo3.org/extension/vite_asset_collector