diff --git a/.editorconfig b/.editorconfig index 48f75bf..13f8820 100644 --- a/.editorconfig +++ b/.editorconfig @@ -23,7 +23,6 @@ indent_style = tab # ReST-Files [*.{rst,rst.txt}] indent_size = 4 -max_line_length = 80 # YAML-Files [*.{yaml,yml}] diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index a24fbdc..b6b4d83 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -10,6 +10,14 @@ jobs: - uses: actions/checkout@v4 + - + name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: 8.3 + extensions: intl, mbstring, pdo_sqlite + ini-file: development + - name: Validate composer.json run: composer validate @@ -62,6 +70,19 @@ jobs: unit-coverage-name: coverage-unit-${{ matrix.php-version }}-${{ matrix.typo3-version }} functional-coverage-name: coverage-functional-${{ matrix.php-version }}-${{ matrix.typo3-version }} + test-doc: + name: Test documentation rendering + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Test if the documentation will render without warnings + run: | + mkdir -p Documentation-GENERATED-temp \ + && docker run --rm --pull always -v $(pwd):/project \ + ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log + coverage: needs: - test diff --git a/.gitignore b/.gitignore index b035a24..0da352a 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,5 @@ /.php-cs-fixer.cache /var /Build/Testing/.phpunit.cache +/Documentation-GENERATED-temp +/fluidDocumentationOutput diff --git a/Build/CodeQuality/.ecrc b/Build/CodeQuality/.ecrc index 35bef2c..224c0a8 100644 --- a/Build/CodeQuality/.ecrc +++ b/Build/CodeQuality/.ecrc @@ -11,7 +11,8 @@ ".DS_Store", ".xsd", ".php-cs-fixer.cache", - "LICENSE" + "LICENSE", + "ViteAssetCollector.json" ], "AllowedContentTypes": [], "PassedFiles": [], diff --git a/Build/Documentation/ViewHelpers.json b/Build/Documentation/ViewHelpers.json new file mode 100644 index 0000000..ac6e554 --- /dev/null +++ b/Build/Documentation/ViewHelpers.json @@ -0,0 +1,5 @@ +{ + "name": "ViteAssetCollector", + "namespaceAlias": "vite", + "targetNamespace": "http://typo3.org/ns/Praetorius/ViteAssetCollector/ViewHelpers" +} diff --git a/Classes/ViewHelpers/Asset/ViteViewHelper.php b/Classes/ViewHelpers/Asset/ViteViewHelper.php index 6a0fd27..37f3d7d 100644 --- a/Classes/ViewHelpers/Asset/ViteViewHelper.php +++ b/Classes/ViewHelpers/Asset/ViteViewHelper.php @@ -10,8 +10,31 @@ use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper; /** - * This ViewHelper adds frontend assets generated by vite to - * TYPO3's asset collector + * The `asset.vite` ViewHelper embeds all JavaScript and CSS belonging to the + * specified vite `entry` using TYPO3's AssetCollector API. + * + * Example + * ======= + * + * .. code-block:: html + * + * + * + * */ final class ViteViewHelper extends AbstractViewHelper { @@ -27,21 +50,21 @@ public function initializeArguments(): void $this->registerArgument( 'manifest', 'string', - 'Path to vite manifest file; if omitted, default manifest from extension configuration will be used instead.' + 'Path to your manifest.json file. If omitted, default manifest from extension configuration will be used instead.' ); $this->registerArgument( 'entry', 'string', - 'Name of entrypoint that should be included; can be omitted if manifest file exists and only contains one entrypoint' + '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.', ); - $this->registerArgument('devTagAttributes', 'array', 'Additional attributes for dev server script tags.', false, []); - $this->registerArgument('scriptTagAttributes', 'array', 'Additional attributes for script tags.', false, []); - $this->registerArgument('addCss', 'boolean', 'Define whether css assets should be included.', false, true); + $this->registerArgument('devTagAttributes', 'array', 'HTML attributes that should be added to script tags that point to the vite dev server', false, []); + $this->registerArgument('scriptTagAttributes', 'array', 'HTML attributes that should be added to script tags for built JavaScript assets', false, []); + $this->registerArgument('addCss', 'boolean', 'If set to "false", CSS files associated with the entry point won\'t be added to the asset collector', false, true); $this->registerArgument('cssTagAttributes', 'array', 'Additional attributes for css link tags.', false, []); $this->registerArgument( 'priority', 'boolean', - 'Define whether the assets should be included before other assets.', + 'Include assets before other assets in HTML', false, false ); diff --git a/Classes/ViewHelpers/Resource/ViteViewHelper.php b/Classes/ViewHelpers/Resource/ViteViewHelper.php index a58a410..dbb0701 100644 --- a/Classes/ViewHelpers/Resource/ViteViewHelper.php +++ b/Classes/ViewHelpers/Resource/ViteViewHelper.php @@ -10,7 +10,30 @@ use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper; /** - * This ViewHelper creates an uri to a specific asset file + * The `resource.vite` ViewHelper extracts the uri to one specific asset file from a vite + * manifest file. If the dev server is used, the dev server uri to the resource is returned. + * + * Example + * ======= + * + * This can be used to preload certain assets in the HTML `` tag: + * + * .. code-block:: html + * + * + * + * + * + * */ final class ViteViewHelper extends AbstractViewHelper { @@ -26,12 +49,12 @@ public function initializeArguments(): void $this->registerArgument( 'manifest', 'string', - 'Path to vite manifest file; if omitted, default manifest from extension configuration will be used instead.' + 'Path to vite manifest file; if omitted, default manifest from extension configuration will be used instead' ); $this->registerArgument( 'file', 'string', - 'Asset file for which uri should be created', + 'Identifier of the desired asset file for which a uri should be generated', true ); } diff --git a/Documentation/Configuration/Index.rst b/Documentation/Configuration/Index.rst new file mode 100644 index 0000000..7c95894 --- /dev/null +++ b/Documentation/Configuration/Index.rst @@ -0,0 +1,62 @@ +.. include:: /Includes.rst.txt + +.. _configuration: + +============= +Configuration +============= + +If you use the default setup, no configuration should be necessary. +However, you can customize almost everything to create your individual +development setup. + +.. _configuration-devserver: + +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 :php:`$TYPO3_CONF_VARS`, for example: + +.. code-block:: php + :caption: config/system/additional.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'); + + +.. _configuration-manifest: + +Change location of manifest.json +================================ + +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. + +If you still use vite < 5, you should to change this to `_assets/vite/manifest.json`. + +.. code-block:: php + :caption: config/system/additional.php + + $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['vite_asset_collector']['defaultManifest'] = 'EXT:sitepackage/Resources/Public/Vite/.vite/manifest.json'; + +If you change the path here, please be aware that you may need to adjust `outDir` in +your `vite.config.js` as well: + +.. code-block:: javascript + :caption: vite.config.js + + export default defineConfig({ + // ... + outDir: 'path/to/sitepackage/Resources/Public/Vite/', + }) + diff --git a/Documentation/DdevSetup.md b/Documentation/DdevSetup.md deleted file mode 100644 index f8242e2..0000000 --- a/Documentation/DdevSetup.md +++ /dev/null @@ -1,60 +0,0 @@ -# Set up Vite AssetCollector in a DDEV project - -## Initial TYPO3 setup - -If you need to setup TYPO3 first, have a look at the official documentation: - -[Set up a new project via DDEV and Composer](https://get.typo3.org/version/12) - -Then you need to create a *sitepackage* extensions where your project's -configuration, templates and frontend assets will be located: - -[Set up your sitepackage](https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/) - -## Setup vite-serve for ddev - -Next, you can setup the vite process in your ddev environment with -[ddev-viteserve](https://github.com/torenware/ddev-viteserve): - -```sh -ddev get torenware/ddev-viteserve -``` - -You should check the created `.ddev/.env` file for the correct configuration, -for example: - -```sh -# start vite -VITE_PROJECT_DIR=. -VITE_PRIMARY_PORT=5173 -VITE_SECONDARY_PORT=5273 -VITE_JS_PACKAGE_MGR=npm -# end vite -``` - -The settings take effect with a restart, then you can start the vite process: - -```sh -ddev restart -ddev vite-serve start -``` - -## Configure vite and set up the extension - -See [extension documentation](../README.md). - -## Switch between development and production - -During development, the vite *watcher* process will provide the assets on-the-fly, -in production the assets need to exist in a built state. By default, the extension -differentiates between development and production based on the `TYPO3_CONTEXT` -environment variable. You can set this variable either in your `.ddev/config.yaml` -in `web_environment` or you can -[setup an .env file for your TYPO3](https://github.com/helhum/dotenv-connector). - -With a **Development** context, you need to run `ddev vite-serve`, either manually -or as a `post-start` hook for ddev. - -With a **Production** context, you need to run `ddev npm exec vite build` before -to create the assets and the manifest file, which will then be picked up by the -ViewHelper. diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt new file mode 100644 index 0000000..d3d2f19 --- /dev/null +++ b/Documentation/Includes.rst.txt @@ -0,0 +1,34 @@ +.. More information about this file: + https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt + +.. ---------- +.. text roles +.. ---------- + +.. role:: aspect(emphasis) +.. role:: bash(code) +.. role:: html(code) +.. role:: js(code) +.. role:: php(code) +.. role:: rst(code) +.. role:: sep(strong) +.. role:: sql(code) + +.. role:: tsconfig(code) + :class: typoscript + +.. role:: typoscript(code) +.. role:: xml(code) + :class: html + +.. role:: yaml(code) + +.. default-role:: code + +.. --------- +.. highlight +.. --------- + +.. By default, code blocks use PHP syntax highlighting + +.. highlight:: php diff --git a/Documentation/Index.rst b/Documentation/Index.rst new file mode 100644 index 0000000..e2480d3 --- /dev/null +++ b/Documentation/Index.rst @@ -0,0 +1,55 @@ +.. include:: /Includes.rst.txt + +.. _start: + +=================== +Vite AssetCollector +=================== + +:Extension key: + vite_asset_collector + +:Package name: + praetorius/vite-asset-collector + +:Version: + |release| + +:Language: + en + +:Author: + Simon Praetorius + +:License: + This document is published under the + `Creative Commons BY 4.0 `__ + license. + +:Rendered: + |today| + +---- + +Vite AssetCollector allows you to use the modern frontend bundler `vite `__ +to build your TYPO3 project's frontend assets. + +---- + +**Table of Contents:** + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + Introduction/Index + Installation/Index + Configuration/Index + Reference/Index + +.. Meta Menu + +.. toctree:: + :hidden: + + Sitemap diff --git a/Documentation/Installation/Index.rst b/Documentation/Installation/Index.rst new file mode 100644 index 0000000..15982e0 --- /dev/null +++ b/Documentation/Installation/Index.rst @@ -0,0 +1,174 @@ +.. include:: /Includes.rst.txt + +.. _installation: + +============ +Installation +============ + +Vite AssetCollector can be installed with composer: + +.. code-block:: sh + + composer req praetorius/vite-asset-collector + +vite and the TYPO3 plugin can be installed with the frontend package manager +of your choice: + +.. tabs:: + + .. group-tab:: npm + + .. code-block:: sh + + npm install --save-dev vite vite-plugin-typo3 + + .. group-tab:: pnpm + + .. code-block:: sh + + pnpm add --save-dev vite vite-plugin-typo3 + + .. group-tab:: yarn + + .. code-block:: sh + + yarn add --dev vite vite-plugin-typo3 + + +.. _getting-started: + +Getting Started +=============== + +Follow these steps to get a basic vite setup for your frontend assets in a +`sitepackage` extension. + +.. _vite-setup: + +Vite Setup +---------- + +To get things started, you need to create a `vite.config.js` in the root of +your project to activate the TYPO3 plugin: + +.. code-block:: javascript + :caption: vite.config.js + + import { defineConfig } from "vite"; + import typo3 from "vite-plugin-typo3"; + + export default defineConfig({ + plugins: [typo3()], + }); + +.. _typo3-setup: + +TYPO3 Setup +----------- + +For each extension, you can define one or multiple vite entrypoints in a json file: + +.. code-block:: json + :caption: sitepackage/Configuration/ViteEntrypoints.json + + [ + "../Resources/Private/Main.entry.js" + ] + + +Then you can use the included ViewHelper to embed your assets. If you use the default +configuration, you only need to specify your entrypoint. + +.. code-block:: html + :caption: Layouts/Default.html + + + + ... + + + +.. _start-vite-server: + +Start Vite Server +----------------- + +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 +correct mode automatically. + +There are several options to do this: + +.. tabs:: + + .. group-tab:: npm (locally) + + Prerequisite is a local node setup and installed dependencies outside of Docker setups. Also, + you need to configure the extension to use the correct server url: + + .. code-block:: php + :caption: config/system/additional.php + + $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['vite_asset_collector']['devServerUri'] = 'http://localhost:5173'; + + Then you can start the server, which usually launches on port `5173`: + + .. code-block:: sh + + npm exec vite + + .. group-tab:: pnpm (locally) + + Prerequisite is a local node setup and installed dependencies outside of Docker setups. + + .. code-block:: php + :caption: config/system/additional.php + + $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['vite_asset_collector']['devServerUri'] = 'http://localhost:5173'; + + + Then you can start the server, which usually launches on port `5173`: + + .. code-block:: sh + + pnpm exec vite + + .. group-tab:: yarn (locally) + + Prerequisite is a local node setup and installed dependencies outside of Docker setups. + + .. code-block:: php + :caption: config/system/additional.php + + $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['vite_asset_collector']['devServerUri'] = 'http://localhost:5173'; + + + Then you can start the server, which usually launches on port `5173`: + + .. code-block:: sh + + yarn exec vite + + .. group-tab:: in DDEV + + Prerequisite is one of the available vite add-ons for DDEV, for example: + + .. code-block:: sh + + ddev get torenware/ddev-viteserve + + Then you can start the server inside DDEV: + + .. code-block:: sh + + ddev vite-serve start + + .. .. code-block:: sh + + .. ddev get ddev-vite-sidecar diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst new file mode 100644 index 0000000..0c8ee96 --- /dev/null +++ b/Documentation/Introduction/Index.rst @@ -0,0 +1,31 @@ +.. include:: /Includes.rst.txt + +.. _introduction: + +============ +Introduction +============ + +.. _what-it-does: + +What does it do? +================ + +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. + +It is recommended to use this extension together with a corresponding vite plugin, however +it's also possible to configure vite manually. + +.. _credits: + +Credits +======= + +This extension is inspired by `typo3-vite-demo `__ +which was created by `Florian Geierstanger `__. diff --git a/Documentation/Reference/IconApi.rst b/Documentation/Reference/IconApi.rst new file mode 100644 index 0000000..311cfb8 --- /dev/null +++ b/Documentation/Reference/IconApi.rst @@ -0,0 +1,29 @@ +:navigation-title: Icon API + +.. include:: /Includes.rst.txt + +.. _icon-api: + +============== +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 +and backend context. + +To register a new icon, add the following to the `Configuration/Icons.php` file: + +.. code-block:: php + :caption: Configuration/Icons.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 :ref:`Icon ViewHelper ` +to use the icon in your templates. diff --git a/Documentation/Reference/Index.rst b/Documentation/Reference/Index.rst new file mode 100644 index 0000000..ce551ae --- /dev/null +++ b/Documentation/Reference/Index.rst @@ -0,0 +1,15 @@ +.. include:: /Includes.rst.txt + +.. _reference: + +========= +Reference +========= + + +.. toctree:: + :titlesonly: + :glob: + + */Index + * diff --git a/Documentation/Reference/ViewHelpers/AssetVite.rst b/Documentation/Reference/ViewHelpers/AssetVite.rst new file mode 100644 index 0000000..e74ea35 --- /dev/null +++ b/Documentation/Reference/ViewHelpers/AssetVite.rst @@ -0,0 +1,12 @@ +:navigation-title: asset.vite + +.. include:: /Includes.rst.txt + +.. _viewhelper-asset-vite: + +========================================= +Asset.vite ViewHelper `` +========================================= + +.. typo3:viewhelper:: asset.vite + :source: ./ViteAssetCollector.json diff --git a/Documentation/Reference/ViewHelpers/Index.rst b/Documentation/Reference/ViewHelpers/Index.rst new file mode 100644 index 0000000..58fe4d6 --- /dev/null +++ b/Documentation/Reference/ViewHelpers/Index.rst @@ -0,0 +1,14 @@ +.. include:: /Includes.rst.txt + +.. _viewhelpers: + +=========== +ViewHelpers +=========== + + +.. toctree:: + :titlesonly: + :glob: + + * diff --git a/Documentation/Reference/ViewHelpers/ResourceVite.rst b/Documentation/Reference/ViewHelpers/ResourceVite.rst new file mode 100644 index 0000000..4a35dc7 --- /dev/null +++ b/Documentation/Reference/ViewHelpers/ResourceVite.rst @@ -0,0 +1,12 @@ +:navigation-title: resource.vite + +.. include:: /Includes.rst.txt + +.. _viewhelper-resource-vite: + +=============================================== +Resource.vite ViewHelper `` +=============================================== + +.. typo3:viewhelper:: resource.vite + :source: ./ViteAssetCollector.json diff --git a/Documentation/Reference/ViewHelpers/ViteAssetCollector.json b/Documentation/Reference/ViewHelpers/ViteAssetCollector.json new file mode 100644 index 0000000..993afac --- /dev/null +++ b/Documentation/Reference/ViewHelpers/ViteAssetCollector.json @@ -0,0 +1 @@ +{"viewHelpers":{"asset.vite":{"className":"Praetorius\\ViteAssetCollector\\ViewHelpers\\Asset\\ViteViewHelper","namespace":"Praetorius\\ViteAssetCollector\\ViewHelpers","name":"Asset\\ViteViewHelper","tagName":"asset.vite","documentation":"The `asset.vite` ViewHelper embeds all JavaScript and CSS belonging to the\nspecified vite `entry` using TYPO3's AssetCollector API.\n\nExample\n=======\n\n.. code-block:: html\n\n \n\n ","xmlNamespace":"http:\/\/typo3.org\/ns\/Praetorius\/ViteAssetCollector\/ViewHelpers","docTags":[],"argumentDefinitions":{"manifest":{"name":"manifest","type":"string","description":"Path to your manifest.json file. If omitted, default manifest from extension configuration will be used instead.","required":false,"defaultValue":null,"escape":null},"entry":{"name":"entry","type":"string","description":"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.","required":false,"defaultValue":null,"escape":null},"devTagAttributes":{"name":"devTagAttributes","type":"array","description":"HTML attributes that should be added to script tags that point to the vite dev server","required":false,"defaultValue":[],"escape":null},"scriptTagAttributes":{"name":"scriptTagAttributes","type":"array","description":"HTML attributes that should be added to script tags for built JavaScript assets","required":false,"defaultValue":[],"escape":null},"addCss":{"name":"addCss","type":"boolean","description":"If set to \"false\", CSS files associated with the entry point won't be added to the asset collector","required":false,"defaultValue":true,"escape":null},"cssTagAttributes":{"name":"cssTagAttributes","type":"array","description":"Additional attributes for css link tags.","required":false,"defaultValue":[],"escape":null},"priority":{"name":"priority","type":"boolean","description":"Include assets before other assets in HTML","required":false,"defaultValue":false,"escape":null},"useNonce":{"name":"useNonce","type":"bool","description":"Whether to use the global nonce value","required":false,"defaultValue":false,"escape":null}},"allowsArbitraryArguments":false,"nameWithoutSuffix":"Asset\\Vite","namespaceWithoutSuffix":"Praetorius\\ViteAssetCollector","uri":"ViteAssetCollector\/Asset\/Vite"},"resource.vite":{"className":"Praetorius\\ViteAssetCollector\\ViewHelpers\\Resource\\ViteViewHelper","namespace":"Praetorius\\ViteAssetCollector\\ViewHelpers","name":"Resource\\ViteViewHelper","tagName":"resource.vite","documentation":"The `resource.vite` ViewHelper extracts the uri to one specific asset file from a vite\nmanifest file. If the dev server is used, the dev server uri to the resource is returned.\n\nExample\n=======\n\nThis can be used to preload certain assets in the HTML `` tag:\n\n.. code-block:: html\n\n \n\n \n \n <\/f:section>","xmlNamespace":"http:\/\/typo3.org\/ns\/Praetorius\/ViteAssetCollector\/ViewHelpers","docTags":[],"argumentDefinitions":{"manifest":{"name":"manifest","type":"string","description":"Path to vite manifest file; if omitted, default manifest from extension configuration will be used instead","required":false,"defaultValue":null,"escape":null},"file":{"name":"file","type":"string","description":"Identifier of the desired asset file for which a uri should be generated","required":true,"defaultValue":null,"escape":null}},"allowsArbitraryArguments":false,"nameWithoutSuffix":"Resource\\Vite","namespaceWithoutSuffix":"Praetorius\\ViteAssetCollector","uri":"ViteAssetCollector\/Resource\/Vite"}},"uri":"ViteAssetCollector\/Index","name":"ViteAssetCollector","label":"ViteAssetCollector","namespaceAlias":"vite","targetNamespace":"http:\/\/typo3.org\/ns\/Praetorius\/ViteAssetCollector\/ViewHelpers","includesNamespaces":["http:\/\/typo3.org\/ns\/Praetorius\/ViteAssetCollector\/ViewHelpers"],"sourceEdit":null,"headlineIdentifierPrefix":null} \ No newline at end of file diff --git a/Documentation/Reference/Yaml.rst b/Documentation/Reference/Yaml.rst new file mode 100644 index 0000000..7875134 --- /dev/null +++ b/Documentation/Reference/Yaml.rst @@ -0,0 +1,26 @@ +:navigation-title: Yaml Processor + +.. include:: /Includes.rst.txt + +.. _yaml-processor: + +========================= +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 +:ref:`custom RTE presets ` + +.. code-block:: yaml + :caption: MyPreset.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')%" diff --git a/Documentation/Sitemap.rst b/Documentation/Sitemap.rst new file mode 100644 index 0000000..cd06f7d --- /dev/null +++ b/Documentation/Sitemap.rst @@ -0,0 +1,9 @@ +:template: sitemap.html + +.. include:: /Includes.rst.txt + +======= +Sitemap +======= + +.. The sitemap.html template will insert here the page tree automatically. diff --git a/Documentation/guides.xml b/Documentation/guides.xml new file mode 100644 index 0000000..c3aa00a --- /dev/null +++ b/Documentation/guides.xml @@ -0,0 +1,34 @@ + + + + + + + + + diff --git a/README.md b/README.md index 3103af0..00b1b0f 100644 --- a/README.md +++ b/README.md @@ -7,267 +7,30 @@ [![TYPO3 versions](https://typo3-badges.dev/badge/vite_assetcollector/typo3/shields.svg)](https://extensions.typo3.org/extension/vite_asset_collector) [![Latest version](https://typo3-badges.dev/badge/vite_assetcollector/version/shields.svg)](https://extensions.typo3.org/extension/vite_asset_collector) -Bundle your TYPO3 frontend assets with **[vite](https://vitejs.dev/)**, a modern -and flexible frontend tool. This TYPO3 extension provides a future-proof -integration for vite using TYPO3's AssetCollector API. -It allows you to use vite's hot reloading and hot module replacement features -(and many others) in your TYPO3 projects. +Vite AssetCollector allows you to use the modern frontend bundler **[vite](https://vitejs.dev/)** +to build your TYPO3 project's frontend assets. -This extension is inspired by -[typo3-vite-demo](https://github.com/fgeierst/typo3-vite-demo) which was created -by [Florian Geierstanger](https://github.com/fgeierst/). +## Documentation -## Installation +**[Documentation on docs.typo3.org](https://docs.typo3.org/p/praetorius/vite-asset-collector/main/)** -Vite AssetCollector can be installed with composer: +### tl;dr ```sh composer req praetorius/vite-asset-collector -``` - -vite and the TYPO3 plugin can be installed with the frontend package manager -of your choice: - -```sh npm install --save-dev vite vite-plugin-typo3 ``` -## Getting Started - -### 1. Vite Setup - -To get things started, you need to create a `vite.config.js` in the root of -your project to activate the TYPO3 plugin: - -```js -import { defineConfig } from "vite"; -import typo3 from "vite-plugin-typo3"; - -export default defineConfig({ - plugins: [typo3()], -}); -``` - -For more information and options about the vite plugin, please refer to its -[documentation](https://github.com/s2b/vite-plugin-typo3/blob/main/README.md). - -### 2. TYPO3 Setup - -For each extension, you can define one or multiple vite entrypoints in a json file: - -**sitepackage/Configuration/ViteEntrypoints.json**: - -```json -[ - "../Resources/Private/Main.entry.js" -] -``` - -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**: - -```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: - -
- 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](https://github.com/torenware/ddev-viteserve) set up - -You can adjust both options in your `$TYPO3_CONF_VARS`, for example: - -```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'); -``` - -
- -
- 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. - -```php -$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['vite_asset_collector']['defaultManifest'] = 'EXT:sitepackage/Resources/Public/Vite/.vite/manifest.json'; -``` - -In your `vite.config.js`: +* Include PlugIn in vite config +* Add `Configuration/ViteEntrypoints.json` to extension(s) +* Add `` to template +* Run vite server +* Have fun! -```js -export default defineConfig({ - // ... - outDir: 'path/to/sitepackage/Resources/Public/Vite/', -}) -``` +## Discussion & Support -
- -## 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. - -
- 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 - -
- -
- Example - -```xml - -``` - -
- - -### resource.vite ViteHelper - -The `resource.vite` ViewHelper extracts the uri to one specific asset file from a vite -manifest file. - -
- 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 - -
- -
- Example - -This can be used to preload certain assets in the HTML `` tag: - -```xml - - - -``` - -
- -## 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](https://docs.typo3.org/c/typo3/cms-rte-ckeditor/main/en-us/Configuration/Examples.html): - -```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](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Icon/Index.html), -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: - -```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 - ], -]; -``` +You can join **[#vite on TYPO3 Slack](https://typo3.slack.com/app_redirect?channel=vite)** +to discuss anything about vite and TYPO3. -Then you can use the [core:icon ViewHelper](https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/typo3/core/latest/Icon.html) -to use the icon in your templates. +Feel free to **[contact me directly](mailto:moin@praetorius.me)** if you are interested +in a (paid) workshop to introduce vite to your TYPO3 projects. diff --git a/composer.json b/composer.json index bcbe025..1e3939b 100644 --- a/composer.json +++ b/composer.json @@ -19,6 +19,9 @@ "saschaegerer/phpstan-typo3": "^1.8", "phpunit/phpunit": "^11.1 || ^10.5" }, + "suggest": { + "t3docs/fluid-documentation-generator": "To update ViewHelper documentation with doc:viewhelpers" + }, "autoload": { "psr-4": { "Praetorius\\ViteAssetCollector\\": "Classes/" @@ -78,6 +81,8 @@ ], "coverage:unit": "phpunit -c Build/Testing/UnitTests.xml --coverage-clover .Build/logs/clover.unit.xml --coverage-php .Build/logs/clover.unit.cov", "coverage:functional": "phpunit -c Build/Testing/FunctionalTests.xml --coverage-clover .Build/logs/clover.functional.xml --coverage-php .Build/logs/clover.functional.cov", - "coverage:report": "phpcov merge --html .Build/logs/report .Build/logs" + "coverage:report": "phpcov merge --html .Build/logs/report .Build/logs", + + "doc:viewhelpers": "fluidDocumentation generate Build/Documentation/ViewHelpers.json && cp fluidDocumentationOutput/ViteAssetCollector.json Documentation/Reference/ViewHelpers/" } }