---
title: "Migration from 1.x to 2.0"
manual: "Vite AssetCollector"
version: "main"
permalink: "https://docs.typo3.org/permalink/praetorius/vite-asset-collector:migration@main"
source: "Migration/Index.rst"
rendered: "2026-11-15T13:51:42+00:00"
---

# Migration from 1.x to 2.0 {#migration}

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.

**Table of contents**

-   [Requirements](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:requirements@main)
-   [Fluid templates](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:fluid-templates@main)
-   [Changed HTML output](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:changed-html-output@main)
-   [PHP API](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:php-api@main)
-   [Removed CLI command](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:removed-cli-command@main)

## Requirements {#migration-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](https://github.com/s2b/vite-plugin-typo3/)
    or set `resolve.preserveSymlinks` to `true` in your `vite.config.js`.

## Fluid templates {#migration-templates}

### Removed ViewHelper aliases {#migration-templates-aliases}

The old ViewHelper names have been removed:

```text
<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> {#migration-templates-arguments}

Most embedding options of [\<vite:asset>](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:viewhelper-asset@main) 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}" />](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:viewhelper-asset-css@main) |
| `inlineCss="1"` | [\<vite:asset.css inline="{true}" />](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:viewhelper-asset-css@main) |
| `cssTagAttributes="{…}"` | [\<vite:asset.css additionalAttributes="{…}" />](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:viewhelper-asset-css@main) |
| `scriptTagAttributes="{…}"` | [\<vite:asset.script additionalAttributes="{…}" />](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:viewhelper-asset-script@main) |
| `priority="1"` | [\<vite:asset.script priority="{true}" />](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:viewhelper-asset-script@main) (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**

```html
<vite:asset
    entry="EXT:sitepackage/Resources/Private/JavaScript/Main.entry.js"
    inlineCss="1"
    scriptTagAttributes="{async: 'async'}"
/>
```

**After**

```html
<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 {#migration-templates-dev-tag-attributes}

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="{…}" />](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:viewhelper-asset-script@main).
They are no longer applied to the `<script>` tag of the Vite client.

### \<vite:uri> returns an URI object {#migration-templates-uri}

[\<vite:uri>](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:viewhelper-uri@main) 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 {#migration-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>](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:viewhelper-asset-script@main),
    [\<vite:asset.font>](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:viewhelper-asset-font@main) and
    [\<vite:asset.image>](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:viewhelper-asset-image@main). 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 {#migration-php}

### Removed ViteService {#migration-php-vite-service}

`PraetoriusViteAssetCollectorServiceViteService` has been removed
and replaced by several smaller services. For most use cases, the new
[ViteHelper](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:php-api-vitehelper@main) 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](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:php-api-vite-context@main) |
| `getDefaultManifestFile()` | `ManifestFactory::getDefault()` |
| `determineEntrypointFromManifest()` | `Manifest::getOnlyEntrypoint()` |

### Vite context {#migration-php-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](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:extending-events-build-vite-context@main).

## Removed CLI command {#migration-cli}

The `vite:config` command has been removed. Use
[vite-plugin-typo3](https://github.com/s2b/vite-plugin-typo3/) or follow the
[manual Vite configuration](https://docs.typo3.org/permalink/praetorius/vite-asset-collector:configuration-vite-manual@main).
