Vite TypeScript Transform Plugin

Common errors

• Syntax Error: Unexpected token '@'

  cause Using new ECMAScript decorators (or legacy decorators with improper configuration) that esbuild does not support, and `vite-plugin-typescript-transform` either isn't configured correctly or is running too late.
  fix Ensure `vite-plugin-typescript-transform` is installed, correctly imported, and configured with `enforce: 'pre'` in your `vite.config.ts`. Additionally, set appropriate TypeScript `target` and `compilerOptions` (e.g., for new decorators, `"target": "ES2021"` or higher in `tsconfig.override`).

• Error: Plugin 'vite-plugin-typescript-transform' is not processing files, or TypeScript features are not being transpiled as expected.

  cause The plugin's configuration is incorrect, or its execution order is clashing with other Vite plugins or Vite's default behavior.
  fix Verify that `enforce: 'pre'` is set in the plugin configuration. Check the `filter` options to ensure the correct file types (e.g., `.ts` files) are being included for transformation. Review `tsconfig.override` for desired `compilerOptions`.

• Failed to parse tsconfig.json: 'extends' is not supported (or similar error regarding tsconfig structure).

  cause Using `extends` in `tsconfig.json` with an older version of the plugin that did not fully support this feature.
  fix Upgrade to `vite-plugin-typescript-transform` version 1.3.0 or higher, which introduced support for the `extends` property in `tsconfig.json`.

Warnings

• breaking The initial v1.0.0 release introduced the core plugin functionality. While not a breaking change from a previous version of this plugin, it established the first stable API, meaning any significant changes in subsequent major versions would be considered breaking against this baseline.
  Fix: Refer to the plugin's documentation for any specific migration paths when upgrading from 1.x to future major versions.
• gotcha This plugin must be configured to run before Vite's default esbuild transpilation to properly apply TypeScript transformations for features not supported by esbuild. Failing to do so can result in syntax errors or incorrect output.
  Fix: Always include `enforce: 'pre'` in the plugin configuration within your `vite.config.ts` file.
• gotcha The plugin does not disable or replace Vite's built-in esbuild compiler. It only pre-processes code using the TypeScript compiler. Esbuild will still process the output from this plugin. Ensure your TypeScript `target` and `tsconfig.override` options align with what esbuild can ultimately handle after the initial TS compilation step.
  Fix: Carefully consider your `tsconfig` options (especially `target`) within the `tsconfig.override` to produce output compatible with esbuild and your target runtime environment.
• gotcha Earlier versions had issues correctly parsing `tsconfig.json` files that used the `extends` property or respecting the `tsconfig.override` option.
  Fix: Upgrade to `v1.3.1` or later to ensure proper handling of `tsconfig.json` extends and `tsconfig.override` functionality. If unable to upgrade, flatten your `tsconfig.json` or manually apply all relevant compiler options.

Install

• npm install vite-plugin-typescript-transform npm
• yarn add vite-plugin-typescript-transform yarn
• pnpm add vite-plugin-typescript-transform pnpm

Imports

• vitePluginTypescriptTransform
  wrong:

  const vitePluginTypescriptTransform = require('vite-plugin-typescript-transform');

  correct:

  import { vitePluginTypescriptTransform } from 'vite-plugin-typescript-transform';

  This plugin is designed for ESM contexts within Vite configurations.
• defineConfig

  import { defineConfig } from 'vite';

  Standard Vite utility for defining configuration, commonly used with this plugin.
• ts

  import ts from 'typescript';

  Often imported to access TypeScript's enums (e.g., ScriptTarget) for plugin options, as seen in the examples.

Quickstart

Demonstrates how to configure the plugin in `vite.config.ts` to apply TypeScript transformation, specifically highlighting the use of `enforce: 'pre'` and `tsconfig.override` for features like ECMAScript decorators.

import ts from 'typescript';
import { defineConfig } from 'vite';
import { vitePluginTypescriptTransform } from 'vite-plugin-typescript-transform';

export default defineConfig({
  plugins: [
    vitePluginTypescriptTransform({
      enforce: 'pre',
      filter: {
        files: {
          include: /\.ts$/,
        },
      },
      tsconfig: {
        override: {
          target: ts.ScriptTarget.ES2021,
          // Enable new ECMAScript decorators support if needed
          // 'experimentalDecorators' is for legacy decorators
          // 'useDefineForClassFields' often needed for new decorators
          // For new decorators, ensure TypeScript version is >=5.0
        },
      },
    }),
  ],
  // ... other vite configuration
});