[DOC] Add best practices and various changes

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 <https://github.com/s2b/vite-plugin-typo3/>`__, 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 <configuration-vite-manual>` 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 <https://en.wikipedia.org/wiki/Glob_(programming)>`__ 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'
+        );
+    }

Documentation/Configuration/Index.rst

@@ -12,37 +12,38 @@ 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 <https://github.com/s2b/ddev-vite-sidecar>`__ or
     `vite-serve for DDEV <https://github.com/torenware/ddev-viteserve>`__ set up
 
 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');
 
 
 ..  _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 <https://github.com/s2b/vite-plugin-typo3/>`__, 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 <https://vitejs.dev/config/shared-options.html#resolve-alias>`__ 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/") }
+            ]
+        }
+    });

Documentation/Index.rst

@@ -31,7 +31,7 @@ Vite AssetCollector
 
 ----
 
-Vite AssetCollector allows you to use the modern frontend bundler `vite <https://vitejs.dev/>`__
+Vite AssetCollector allows you to use the modern frontend bundler `Vite <https://vitejs.dev/>`__
 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
 

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 <https://github.com/s2b/vite-plugin-typo3/blob/main/README.md>`__.
+
 ..  _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