Migration from 1.x to 2.0 

Version 2 is a major overhaul of the internal code structure as well as the PHP API (i. e. the PraetoriusViteAssetCollectorServiceViteService class). The API of the ViewHelpers stays mostly the same, however some of the ViewHelper arguments are now deprecated and should be migrated to their new equivalent. Also, the old ViewHelper names <vac:asset.vite> and <vac:resource.vite>, which have been deprecated already, no longer work with version 2.

The extension remains compatible with TYPO3 v13 and v14, but now requires Vite 5 or higher.

Requirements 

  • PHP (8.2+) and TYPO3 (v13+v14) requirements remain the same.
  • Vite 5 or higher is required. The legacy location of the manifest file without the .vite/ folder is no longer supported.
  • Symlinked entry points are no longer resolved to their original path. Use version 3 of vite-plugin-typo3 or set resolve.preserveSymlinks to true in your vite.config.js.

Fluid templates 

Removed ViewHelper aliases 

The old ViewHelper names have been removed:

<vac:asset.vite>     => <vite:asset>
<vac:resource.vite>  => <vite:uri>
Copied!

The vite namespace is now registered globally, so explicit namespace declarations for the extension is no longer necessary.

Deprecated arguments of <vite:asset> 

Most embedding options of <vite:asset> have been moved to the new child ViewHelpers. The old arguments still work in 2.x, but trigger deprecation notices and will be removed with 3.0.

Deprecated argument Replacement
addCss="0" <vite:asset.css ignore="{true}" />
inlineCss="1" <vite:asset.css inline="{true}" />
cssTagAttributes="{…}" <vite:asset.css additionalAttributes="{…}" />
scriptTagAttributes="{…}" <vite:asset.script additionalAttributes="{…}" />
priority="1" <vite:asset.script priority="{true}" /> (CSS is added with priority by default now)
useNonce="1" csp="{true}"

Once <vite:asset.css> or <vite:asset.script> is used, the deprecated arguments can no longer be combined with them in the same <vite:asset> tag.

Example:

Before
<vite:asset
    entry="EXT:sitepackage/Resources/Private/JavaScript/Main.entry.js"
    inlineCss="1"
    scriptTagAttributes="{async: 'async'}"
/>
Copied!
After
<vite:asset entry="EXT:sitepackage/Resources/Private/JavaScript/Main.entry.js">
    <vite:asset.css inline="{true}" />
    <vite:asset.script async="{true}" />
</vite:asset>
Copied!

Removed argument devTagAttributes 

The devTagAttributes argument of <vite:asset> has been removed. Additional script attributes are now applied consistently in development and production via <vite:asset.script additionalAttributes="{…}" />. They are no longer applied to the <script> tag of the Vite client.

<vite:uri> returns an URI object 

<vite:uri> now returns an object implementing PsrHttpMessageUriInterface instead of a string. In most templates this makes no difference, since the object is converted to a string automatically.

Changed HTML output 

The following changes affect the generated HTML without any changes to your templates:

  • Automatic preloading: Imported JavaScript modules are preloaded with <link rel="modulepreload"> and referenced fonts in the woff2 format with <link rel="preload">. This can be configured with <vite:asset.script preloadImports>, <vite:asset.font> and <vite:asset.image>. Manual preloading with <vite:uri> can be removed in most cases.
  • CSS priority: CSS files are added with priority=true by default, which places them before other stylesheets in the <head>.
  • Duplicate CSS: The same CSS file is embedded again if it is requested with different tag attributes (e. g. a different media query).
  • Asset identifiers: The identifiers of assets in TYPO3's AssetCollector have changed. Code that accesses or removes Vite assets from the AssetCollector by their identifier needs to be adjusted.

PHP API 

Removed ViteService 

PraetoriusViteAssetCollectorServiceViteService has been removed and replaced by several smaller services. For most use cases, the new ViteHelper is the recommended replacement:

ViteService (1.x) Replacement (2.0)
addAssetsFromManifest(), addAssetsFromDevServer() ViteHelper::renderAsset(), or AssetRendererInterface::renderBuildAsset() / AssetRendererInterface::renderDevAsset()
getAssetPathFromManifest(), getAssetPathFromDevServer() ViteHelper::generateUri(), or AssetUriGeneratorInterface::generateUri() / AssetUriGeneratorInterface::generateDevUri()
useDevServer(), determineDevServer() Request attribute vite.context, see Vite context
getDefaultManifestFile() ManifestFactory::getDefault()
determineEntrypointFromManifest() Manifest::getOnlyEntrypoint()

Vite context 

Whether the dev server is used is now determined once per request and stored in the vite.context request attribute. To customize this, use the BuildViteContextEvent.

Removed CLI command 

The vite:config command has been removed. Use vite-plugin-typo3 or follow the manual Vite configuration.