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 `