[Vite 8] How to use stage 3 decorators?

[dirkluijk]

In our organization we're using stage 3 decorators quite a lot: in some internal libraries, but also with this open source library. Our main rationale is to move towards ECMAScript standards instead of keeping legacy TypeScript decorators "alive".

This worked fine with Vite 7:

import { defineConfig } from "vite";

export default defineConfig(() => ({
  esbuild: {
    target: "es2022",
  },
}));

However, with Vite 8 we now have a big problem: since it's dropping esbuild in favor of Rolldown (with oxc), we're getting

SyntaxError: Invalid or unexpected token

Now our whole tool chain breaks down — since, we're also using Vitest.

Is there a workaround? Or should we rewrite all our libraries to use the legacy TypeScript decorators instead?

[travisbreaks]

Oxc (which replaced esbuild in Vite 8) does not support lowering TC39 Stage 3 decorators. Legacy TS decorators (experimentalDecorators: true) work, but native/ECMA decorators do not. The tracking issue is oxc#9170, open with no timeline. Rolldown's equivalent (rolldown#7327) is labeled bug: upstream, blocked on Oxc.

The workaround from the Vite 8 migration guide: use @rolldown/plugin-babel with @babel/plugin-proposal-decorators. The filter: { code: "@" } option ensures Babel only runs on files that contain decorators, keeping perf impact minimal.

import babel from "@rolldown/plugin-babel"

export default defineConfig({
  plugins: [
    babel({
      presets: [{
        preset: () => ({ plugins: [["@babel/plugin-proposal-decorators", { version: "2023-11" }]] }),
        rolldown: { filter: { code: "@" } },
      }],
    }),
  ],
})

SWC is also an option via unplugin-swc, but it only supports the older 2022-03 spec revision. Same plugin config applies to Vitest if you extend your Vite config. There is no esbuild fallback; the esbuild config key still exists but auto-converts to Oxc equivalents.

[chandrika1993]

We hit the same issue with Stage 3 decorators after upgrading to Vite 8.

Current workaround is @rolldown/plugin-babel with @babel/plugin-proposal-decorators using "2023-11":

import { defineConfig } from "vite";
import babel from "@rolldown/plugin-babel";

function decoratorPreset(options: Record<string, unknown>) {
  return {
    preset: () => ({
      plugins: [["@babel/plugin-proposal-decorators", options]],
    }),
    rolldown: {
      filter: { code: "@" },
    },
  };
}

export default defineConfig({
  plugins: [
    babel({
      presets: [decoratorPreset({ version: "2023-11" })],
    }),
  ],
});

npm install -D @rolldown/plugin-babel @babel/plugin-proposal-decorators

"2023-11" is currently the safest choice because it matches the latest Stage 3 decorators semantics.

[Kapelianovych]

None of the proposed solutions work when the class' name is used by the decorator: Babels strips names and SWC generates assignment to class' name property causing "TypeError: Attempted to assign to readonly property.".

[tquangtri]

Downgrade your tsconfig target to es2023 instead of esnext like so

{
  "compilerOptions": {
    "target": "es2023",
    "module": "esnext",
    "lib": [
    ...

Then use esbuild' transform feature as an in-between plugin.

import {transform} from 'esbuild';
import type {Plugin} from 'vite';

const DECORATOR_RE = /(?:^|\n)\s*@[A-Za-z_$][\w$]*(?:\s|\.|\()/;
const TYPESCRIPT_RE = /\.(?:[cm]?ts|tsx)(?:\?|$)/;

export function stage3DecoratorTransform(): Plugin {
    return {
        name: 'oh-my:stage-3-cheat',
        enforce: 'pre',
        transform: {
            filter: {
                moduleType: ['js', 'jsx', 'ts', 'tsx'],
                id: TYPESCRIPT_RE,
                code: DECORATOR_RE,
            },
            async handler(code, id) {
                const cleanId = id.split('?', 1)[0];
                const result = await transform(code, {
                    loader: cleanId.endsWith('x') ? 'tsx' : 'ts',
                    target: 'es2023',
                    format: 'esm',
                    jsx: 'preserve',
                    sourcefile: cleanId,
                    sourcemap: true,
                });

                return {code: result.code, map: result.map};
            },
        },
    }
}

Then add it to your plugin list in vite config

...
plugins: [
 yourOtherPluginsA(),
 stage3DecoratorTransform(),
 yourOtherPluginsB(),
 ...

You can safely re-install esbuild. Don't worry, vite still won't use it, only this plugin does.
This is ugly, but it's just a temporally solution, no better way till Vite provide an alternative

[Nithwin]

To summarize the current state since several partial answers have been posted:

The core issue

Oxc (which replaced esbuild in Vite 8/Rolldown) does not support lowering TC39 Stage 3 (2023-11 spec) decorators. There's no timeline on the upstream fix: oxc-project/oxc#9170. Legacy TypeScript experimentalDecorators still works because Oxc does handle those.

Working solutions today

Option 1 — Babel plugin (recommended for most cases)

From the Vite 8 migration guide:

npm install -D @rolldown/plugin-babel @babel/plugin-proposal-decorators

// vite.config.ts
import { defineConfig } from "vite";
import babel from "@rolldown/plugin-babel";

export default defineConfig({
  plugins: [
    babel({
      presets: [{
        preset: () => ({
          plugins: [["@babel/plugin-proposal-decorators", { version: "2023-11" }]]
        }),
        rolldown: { filter: { code: "@" } }, // only run on files with decorators
      }],
    }),
  ],
});

The filter: { code: "@" } keeps perf impact minimal. This also works in Vitest if you extend the same config.

Option 2 — esbuild as a pre-transform plugin (handles the class-name issue)

If you hit TypeError: Attempted to assign to readonly property when the decorator references the class's own name (which Babel strips), this custom plugin avoids that by running esbuild's transform before Oxc sees the file:

// vite.config.ts
import { transform } from "esbuild";
import type { Plugin } from "vite";

const DECORATOR_RE = /(?:^|\n)\s*@[A-Za-z_$][\w$]*(?:\s|\.|\()/;
const TS_RE = /\.(?:[cm]?ts|tsx)(?:\?|$)/;

function stage3DecoratorTransform(): Plugin {
  return {
    name: "stage3-decorator-compat",
    enforce: "pre",
    transform: {
      filter: { moduleType: ["js", "jsx", "ts", "tsx"], id: TS_RE, code: DECORATOR_RE },
      async handler(code, id) {
        const cleanId = id.split("?", 1)[0];
        const result = await transform(code, {
          loader: cleanId.endsWith("x") ? "tsx" : "ts",
          target: "es2023",
          format: "esm",
          jsx: "preserve",
          sourcefile: cleanId,
          sourcemap: true,
        });
        return { code: result.code, map: result.map };
      },
    },
  };
}

export default defineConfig({
  plugins: [stage3DecoratorTransform(), /* other plugins */],
});

You can npm install -D esbuild safely — Vite 8 won't use it internally, only this plugin does.

Option 3 — Fall back to legacy decorators (not recommended if you're targeting ECMAScript standard)

Set experimentalDecorators: true in tsconfig.json. This works but moves you further from the Stage 3 standard.

Vitest note

Both Options 1 and 2 work with Vitest when you extend the same Vite config. Option 2's esbuild approach is synchronous and has no config overlap with Vitest's runner.

TL;DR: Use Option 1 unless you're hitting the class-name issue, then use Option 2.

Option 4 — SWC as a Rolldown plugin

If you prefer SWC over Babel or esbuild, you can use the SWC plugin for Rolldown to handle the decorator transformation.

Example configuration (thanks to @TechQuery):

import { defineConfig } from "vite";
import swc from "unplugin-swc";

export default defineConfig({
  plugins: [
    swc.vite({
      jsc: {
        parser: {
          syntax: "typescript",
          decorators: true,
        },
        transform: {
          legacyDecorator: false,
          decoratorMetadata: true,
        },
      },
    }),
  ],
});

[TechQuery]

Option 4: Use SWC as Rolldown plugin: https://github.com/idea2app/Idea-React/blob/fa8c4520a0c0eaf6d02e96009c382e9dbc90c0c6/tsdown.config.mts#L5-L23

[Nithwin]

"Thanks for sharing this, @TechQuery! Using SWC is a great alternative. I’ve updated the summary to include this as Option 4 so everything is in one place."

Option 4: Use SWC as Rolldown plugin: https://github.com/idea2app/Idea-React/blob/fa8c4520a0c0eaf6d02e96009c382e9dbc90c0c6/tsdown.config.mts#L5-L23