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 Praetorius
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: and
<vac:, 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.
Table of contents
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.topreserve Symlinks truein yourvite..config. js
Fluid templates
Removed ViewHelper aliases
The old ViewHelper names have been removed:
<vac:asset.vite> => <vite:asset>
<vac:resource.vite> => <vite:uri>
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 |
|---|---|
add | <vite:asset.css ignore="{true}" /> |
inline | <vite:asset.css inline="{true}" /> |
css | <vite:asset.css additionalAttributes="{…}" /> |
script | <vite:asset.script additionalAttributes="{…}" /> |
priority="1" | <vite:asset.script priority="{true}" /> (CSS is added with priority by default now) |
use | csp=" |
Once <vite: or <vite: is used, the deprecated
arguments can no longer be combined with them in the same <vite:
tag.
Example:
<vite:asset
entry="EXT:sitepackage/Resources/Private/JavaScript/Main.entry.js"
inlineCss="1"
scriptTagAttributes="{async: 'async'}"
/>
<vite:asset entry="EXT:sitepackage/Resources/Private/JavaScript/Main.entry.js">
<vite:asset.css inline="{true}" />
<vite:asset.script async="{true}" />
</vite:asset>
Removed argument devTagAttributes
The dev argument of <vite: 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
Psr 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:can be removed in most cases.uri> - CSS priority: CSS files are added with
priority=trueby 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
mediaquery). - Asset identifiers: The identifiers of assets in TYPO3's
Assethave changed. Code that accesses or removes Vite assets from theCollector Assetby their identifier needs to be adjusted.Collector
PHP API
Removed ViteService
Praetorius 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) |
|---|---|
add, add | Vite, or
Asset /
Asset |
get, get | Vite, or
Asset /
Asset |
use, determine | Request attribute vite., see
Vite context |
get | Manifest |
determine | Manifest:: |
Vite context
Whether the dev server is used is now determined once per request and stored
in the vite. request attribute. To customize this, use the
BuildViteContextEvent.
Removed CLI command
The vite: command has been removed. Use
vite-plugin-typo3 or follow the
manual Vite configuration.