diff --git a/Documentation/BestPractices/Index.rst b/Documentation/BestPractices/Index.rst
new file mode 100644
index 0000000..4790e6d
--- /dev/null
+++ b/Documentation/BestPractices/Index.rst
@@ -0,0 +1,159 @@
+.. include:: /Includes.rst.txt
+
+.. _bestpractices:
+
+==============
+Best Practices
+==============
+
+.. _project-structure:
+
+Project Structure
+=================
+
+It is recommended to put your `package.json` and your `vite.config.js` next to the `composer.json`
+in the project root. Vite will be responsible for your whole project, so it makes sense to treat your
+frontend dependencies similar to your PHP dependencies.
+
+There are multiple ways to structure your frontend assets in TYPO3 projects. If you want to use the
+`Vite plugin `__, it is recommended to place all your
+frontend assets inside TYPO3 extensions, from where they can automatically get picked up, for
+example:
+
+.. directory-tree::
+
+ * :path:`node_modules`
+ * :path:`packages`
+ * :path:`sitepackage`
+ * :path:`Configuration`
+ * :file:`ViteEntrypoints.json`
+ * :path:`Resources`
+ * :path:`Private`
+ * :file:`Main.entry.js`
+ * :file:`Slider.entry.js`
+ * :path:`my_custom_ext`
+ * :path:`Configuration`
+ * :file:`ViteEntrypoints.json`
+ * :path:`Resources`
+ * :path:`Private`
+ * :file:`MyCustomExt.entry.js`
+ * :path:`vendor`
+ * :file:`composer.json`
+ * :file:`package.json`
+ * :file:`vite.config.js`
+
+
+Different Folder Structures
+---------------------------
+
+If you want to put your frontend assets separately, for example in a `frontend/` folder in your project
+root, you are better off :ref:`configuring Vite yourself ` and not using the Vite plugin.
+The TYPO3 extension doesn't require a specific folder structure, as long as you take care to set the paths correctly
+both in `vite.config.js` and in the extension configuration.
+
+.. _entrypoint-files:
+
+Entrypoint Files
+================
+
+It is recommended to name your entrypoint files differently from other asset files to clarify their usage.
+It might also make sense to use entrypoint files only to create a collection of assets that should become
+one bundle:
+
+.. code-block:: javascript
+ :caption: Slider.entry.js
+
+ import "path/to/Slider.js"
+ import "swiper/css"
+ import "path/to/Slider.css"
+
+.. _glob-imports:
+
+Glob Imports
+============
+
+It is possible to use `glob patterns `__ to import/collect
+several assets at once. This can make your setup much more flexible. *Glob* can be used both in
+`ViteEntrypoints.json` and in your entrypoint files:
+
+.. code-block:: json
+ :caption: sitepackage/Configuration/ViteEntrypoints.json
+
+ [
+ "../Resources/Private/*.entry.js"
+ ]
+
+In entrypoint files, you can use :javascript:`{ eager: true }` to force Vite to collect everything:
+
+.. code-block:: javascript
+ :caption: Main.entry.js
+
+ // Import all CSS files
+ import.meta.glob(
+ "path/to/*.css",
+ { eager: true }
+ )
+
+More complex expressions are also possible, like negative patterns:
+
+.. code-block:: javascript
+ :caption: Main.entry.js
+
+ // Import everything except Slider
+ import.meta.glob([
+ "Components/**/*.{css,js}",
+ '!**/Organism/Slider/*'
+ ], { eager: true })
+
+.. _css-preprocessors:
+
+CSS Preprocessors
+=================
+
+If you want to use Vite to compile your SCSS or LESS files, you need to install the required JavaScript
+libraries as well. No further configuration is necessary.
+
+.. tabs::
+
+ .. group-tab:: npm
+
+ .. code-block:: sh
+
+ npm install --save-dev sass
+ npm install --save-dev less
+ npm install --save-dev stylus
+
+ .. group-tab:: pnpm
+
+ .. code-block:: sh
+
+ pnpm add --save-dev sass
+ pnpm add --save-dev less
+ pnpm add --save-dev stylus
+
+ .. group-tab:: yarn
+
+ .. code-block:: sh
+
+ yarn add --dev sass
+ yarn add --dev less
+ yarn add --dev stylus
+
+.. _aliases:
+
+Referencing Assets in CSS
+=========================
+
+If you use the Vite plugin, it automatically registers an alias for each TYPO3 extension, which allows you
+to reference other assets (like webfonts, svg images...) easily in your CSS files. This also works for CSS
+preprocessors:
+
+.. code-block:: css
+ :caption: _Fonts.scss
+
+ @font-face {
+ font-family: 'MyFont';
+ src: url(
+ '@sitepackage/Resources/.../MyFont.eot'
+ );
+ }
diff --git a/Documentation/Configuration/Index.rst b/Documentation/Configuration/Index.rst
index 36404aa..9a7b348 100644
--- a/Documentation/Configuration/Index.rst
+++ b/Documentation/Configuration/Index.rst
@@ -12,14 +12,15 @@ development setup.
.. _configuration-devserver:
-Adjust vite dev server
+Adjust Vite Dev Server
======================
-The extension has two configuration options to setup the 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-sidecar `__ or
`vite-serve for DDEV `__ set up
You can adjust both options in your :php:`$TYPO3_CONF_VARS`, for example:
@@ -27,7 +28,7 @@ You can adjust both options in your :php:`$TYPO3_CONF_VARS`, for example:
.. code-block:: php
:caption: config/system/additional.php
- // Setup vite dev server based on configuration in .env file
+ // 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');
@@ -35,14 +36,14 @@ You can adjust both options in your :php:`$TYPO3_CONF_VARS`, for example:
.. _configuration-manifest:
-Change location of manifest.json
+Change Location of manifest.json
================================
-You can specify the path to vite's `manifest.json` in the extension configuration.
+You can specify the path to Vite's `manifest.json` 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 and the vite TYPO3 plugin.
+out-of-the-box with Vite 5 and the Vite TYPO3 plugin.
-If you still use vite < 5, you should to change this to `_assets/vite/manifest.json`.
+If you still use Vite < 5, you should to change this to `_assets/vite/manifest.json`.
.. code-block:: php
:caption: config/system/additional.php
@@ -63,3 +64,87 @@ your `vite.config.js` as well:
}
})
+
+.. _configuration-vite-manual:
+
+Manual Vite Configuration
+=========================
+
+If you don't want or can't use the `Vite plugin `__, you can configure
+Vite yourself to work together with the TYPO3 extension. In that case, it is highly recommended to install
+`vite-plugin-auto-origin`:
+
+.. tabs::
+
+ .. group-tab:: npm
+
+ .. code-block:: sh
+
+ npm install --save-dev vite-plugin-auto-origin
+
+ .. group-tab:: pnpm
+
+ .. code-block:: sh
+
+ pnpm add --save-dev vite-plugin-auto-origin
+
+ .. group-tab:: yarn
+
+ .. code-block:: sh
+
+ yarn add --dev vite-plugin-auto-origin
+
+The manual Vite configuration could look something like this:
+
+.. code-block:: javascript
+ :caption: vite.config.js
+
+ import { defineConfig } from "vite"
+ import { dirname, resolve } from "node:path"
+ import { fileURLToPath } from "node:url"
+ import autoOrigin from "vite-plugin-auto-origin"
+
+ // TYPO3 root path (relative to this config file)
+ const VITE_TYPO3_ROOT = "./";
+
+ // Vite input files (relative to TYPO3 root path)
+ const VITE_ENTRYPOINTS = [
+
+ ];
+
+ // Output path for generated assets
+ const VITE_OUTPUT_PATH = "public/_assets/vite/";
+
+ const currentDir = dirname(fileURLToPath(import.meta.url));
+ const rootPath = resolve(currentDir, VITE_TYPO3_ROOT);
+ export default defineConfig({
+ base: "",
+ build: {
+ manifest: true,
+ rollupOptions: {
+ input: VITE_ENTRYPOINTS.map(entry => resolve(rootPath, entry)),
+ },
+ outDir: resolve(rootPath, VITE_OUTPUT_PATH),
+ },
+ css: {
+ devSourcemap: true,
+ },
+ plugins: [ autoOrigin() ],
+ publicDir: false,
+ });
+
+You can also `create aliases yourself `__ to
+refer to other assets in CSS files:
+
+.. code-block:: javascript
+ :caption: vite.config.js
+
+ //...
+ export default defineConfig({
+ // ...
+ resolve: {
+ alias: [
+ { find: "@frontend", replacement: resolve(currentDir, "frontend/") }
+ ]
+ }
+ });
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
index e2480d3..066194d 100644
--- a/Documentation/Index.rst
+++ b/Documentation/Index.rst
@@ -31,7 +31,7 @@ Vite AssetCollector
----
-Vite AssetCollector allows you to use the modern frontend bundler `vite `__
+Vite AssetCollector allows you to use the modern frontend bundler `Vite `__
to build your TYPO3 project's frontend assets.
----
@@ -44,6 +44,7 @@ to build your TYPO3 project's frontend assets.
Introduction/Index
Installation/Index
+ BestPractices/Index
Configuration/Index
Reference/Index
diff --git a/Documentation/Installation/Index.rst b/Documentation/Installation/Index.rst
index 65378a2..4732f17 100644
--- a/Documentation/Installation/Index.rst
+++ b/Documentation/Installation/Index.rst
@@ -12,7 +12,7 @@ Vite AssetCollector can be installed with composer:
composer req praetorius/vite-asset-collector
-vite and the TYPO3 plugin can be installed with the frontend package manager
+Vite and the TYPO3 plugin can be installed with the frontend package manager
of your choice:
.. tabs::
@@ -41,7 +41,7 @@ of your choice:
Getting Started
===============
-Follow these steps to get a basic vite setup for your frontend assets in a
+Follow these steps to get a basic Vite setup for your frontend assets in a
`sitepackage` extension.
.. _vite-setup:
@@ -62,12 +62,14 @@ your project to activate the TYPO3 plugin:
plugins: [typo3()],
});
+For more information about the Vite plugin, have a look at its `dedicated documentation `__.
+
.. _typo3-setup:
TYPO3 Setup
-----------
-For each extension, you can define one or multiple vite entrypoints in a json file:
+For each extension, you can define one or multiple Vite entrypoints in a json file:
.. code-block:: json
:caption: sitepackage/Configuration/ViteEntrypoints.json
@@ -99,7 +101,7 @@ configuration, you only need to specify your entrypoint.
Start Vite Server
-----------------
-For local development, you need a running vite server that serves your frontend assets
+For local development, you need a running Vite server that serves your frontend assets
alongside the normal webserver. On production systems, this is no longer necessary.
First, TYPO3 needs to run in `Development` context for the extension to recognize the
@@ -173,3 +175,30 @@ You have several options to run the dev server:
.. code-block:: sh
yarn exec vite
+
+.. _build_for_production:
+
+Build for Production
+--------------------
+
+During deployment, the following command builds static asset files that can be used in Production:
+
+.. tabs::
+
+ .. group-tab:: npm
+
+ .. code-block:: sh
+
+ npm exec vite build
+
+ .. group-tab:: pnpm
+
+ .. code-block:: sh
+
+ pnpm exec vite build
+
+ .. group-tab:: yarn
+
+ .. code-block:: sh
+
+ yarn exec vite -- build
diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst
index 0c8ee96..25ae378 100644
--- a/Documentation/Introduction/Index.rst
+++ b/Documentation/Introduction/Index.rst
@@ -11,16 +11,53 @@ Introduction
What does it do?
================
-Vite AssetCollector allows you to use the modern frontend bundler `vite `__
+Vite AssetCollector allows you to use the modern frontend bundler `Vite `__
to build your TYPO3 project's frontend assets.
Vite supports all common CSS processors and TypeScript out-of-the-box and has a wide range
of well-supported plugins for popular frontend frameworks. Its hot module replacement feature
allows you to develop your frontend assets without constantly reloading the browser to see your
-changes. As a bonus, vite offers a simple configuration and is easy to use.
+changes. As a bonus, Vite offers a simple configuration and is easy to use.
-It is recommended to use this extension together with a corresponding vite plugin, however
-it's also possible to configure vite manually.
+The extension is necessary both on development and on production systems because it needs to treat
+these environments differently.
+
+It is recommended to use this extension together with a corresponding Vite plugin, however
+it's also possible to configure Vite manually.
+
+.. _components:
+
+Components
+==========
+
+There are two additional projects that can be used in combination with the TYPO3 extension. When used together,
+the setup experience is seamless and requires almost no configuration.
+
+Vite AssetCollector
+-------------------
+
+(this TYPO3 extension)
+
+* switches between Development and Production integration
+* brings tools to embed assets from Vite in TYPO3 (like ViewHelpers)
+
+
+Vite Plugin
+-----------
+
+(`vite-plugin-typo3 `__)
+
+* configures Vite for TYPO3
+* discovers and bundles TYPO3 extensions in composer project
+
+
+DDEV Add-On
+-----------
+
+(`ddev-vite-sidecar `__)
+
+* allows to run the Vite development server inside ddev setups
+* supports Apache and Nginx
.. _credits:
diff --git a/Documentation/Reference/IconApi.rst b/Documentation/Reference/IconApi.rst
index 311cfb8..45978b0 100644
--- a/Documentation/Reference/IconApi.rst
+++ b/Documentation/Reference/IconApi.rst
@@ -9,7 +9,7 @@ TYPO3 Icon API
==============
The extension includes a custom `SvgIconProvider` for the :ref:`TYPO3 Icon API `
-which allows you to register SVG icon files generated by vite. This works both in frontend
+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:
diff --git a/Documentation/Reference/Yaml.rst b/Documentation/Reference/Yaml.rst
index 7875134..8dfb91c 100644
--- a/Documentation/Reference/Yaml.rst
+++ b/Documentation/Reference/Yaml.rst
@@ -9,7 +9,7 @@ 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
+which allows you to use assets generated by Vite in your configuration
files. This is especially useful for
:ref:`custom RTE presets `