vite-plugin-swc-transform

1.1.1 verified Mon Apr 27 auth: no javascript

Vite plugin to transform TypeScript/JavaScript source files with SWC during the build process. Current stable version is 1.1.1, released with support for Vite 5, 6, and 7. It provides sane defaults for legacy/experimental decorators and metadata, and gives full control over SWC configuration. Unlike esbuild (Vite's default), it supports TypeScript legacy decorators with metadata. ESM-only, ships TypeScript declarations, and requires Node >=18.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. ↓

cause Package is ESM-only but imported using require()

fix

Use import statement or dynamic import(). Ensure project type is 'module' in package.json.

error TypeError: swc is not a function ↓

cause Attempting to import the default export as a named export

fix

Use import swc from 'vite-plugin-swc-transform' (no curly braces).

error Warning: SWC option 'jsc.transform.legacyDecorator' enabled without an explicit 'jsc.transform.useDefineForClassFields' value. ↓

cause legacyDecorator is true but useDefineForClassFields is not set

fix

Set 'useDefineForClassFields' to false (or true) in swcOptions.jsc.transform.

Warnings

deprecated TypeScript legacy decorators (experimentalDecorators) are deprecated and will be removed in future TypeScript versions. ↓

fix Migrate to TC39 stage 3 decorators when possible; use SWC's new decorator options.

gotcha Plugin ignores tsconfig.json; SWC options must be explicitly provided. ↓

fix Set all needed SWC options in swcOptions; do not rely on tsconfig.json.

gotcha Package is ESM-only; require() will throw a runtime error. ↓

fix Use import syntax or dynamic import(). Ensure project is configured for ESM.

gotcha When using legacyDecorator: true without an explicit useDefineForClassFields, a warning is emitted. ↓

fix Set 'useDefineForClassFields: false' (or true) explicitly, or set suppressLegacyDecoratorNoExplicitUDFCFWarning: true.

gotcha Using externalHelpers: true requires installing @swc/helpers as a dependency. ↓

fix Add '@swc/helpers' to your project's dependencies.

gotcha The plugin transforms files only during build, not dev server middleware (HMR). ↓

fix For dev transformations, use SWC via Vite's esbuild or another plugin like vite-plugin-esbuild.

Install

npm install vite-plugin-swc-transform

yarn add vite-plugin-swc-transform

pnpm add vite-plugin-swc-transform

Imports

default

wrong

const swc = require('vite-plugin-swc-transform')

correct

import swc from 'vite-plugin-swc-transform'

Package is ESM-only; CommonJS require will fail.

swc

wrong

import { swc } from 'vite-plugin-swc-transform'

correct

import swc from 'vite-plugin-swc-transform'

Package exports only a default export.

SwcOptions

wrong

import { SwcOptions } from 'vite-plugin-swc-transform'

correct

import type { SwcOptions } from 'vite-plugin-swc-transform'

SwcOptions is a type; use import type or import { type SwcOptions }.

Quickstart

Enables legacy decorators with metadata transformation using SWC in Vite build.

import { defineConfig } from 'vite';
import swc from 'vite-plugin-swc-transform';

export default defineConfig({
  plugins: [
    swc({
      swcOptions: {
        jsc: {
          target: 'es2022',
          transform: {
            legacyDecorator: true,
            decoratorMetadata: true,
            useDefineForClassFields: false,
          },
        },
      },
    }),
  ],
});