vite-plugin-tsc-build

0.3.0 verified Fri May 01 auth: no javascript

A Vite plugin that replaces esbuild with the TypeScript compiler (tsc -b) for production builds. Enables support for TypeScript features not handled by Vite's default esbuild bundler, such as isolatedModules: false, implicit type-only imports, and cross-module const enum inlining. Compatible with Vite 4, 5, 6, and 7. Current version is 0.3.0; release cadence is irregular. Differentiator: preserves full tsc semantics for projects that need strict TypeScript compilation during build, at the cost of slower builds.

Common errors

error Error: The plugin must be instantiated with options. ↓

cause The plugin is used without calling it as a function, e.g., plugins: [tscBuildPlugin] instead of plugins: [tscBuildPlugin({})].

fix

Invoke the plugin: tscBuildPlugin({ enabled: true })

error tsc: command not found ↓

cause TypeScript is not installed or not in PATH.

fix

Run npm install --save-dev typescript. Ensure node_modules/.bin is in your PATH or use npx tsc.

error error TS5094: Function calls are not allowed in a file without '--isolatedModules'. ↓

cause The plugin may be processing files with TypeScript features that require isolatedModules: false, but the tsconfig has isolatedModules: true.

fix

Set 'isolatedModules': false in your tsconfig.json (only if you need features like implicit type-only imports).

error Cannot find module 'vite-plugin-tsc-build' or its corresponding type declarations. ↓

cause The package is missing or is installed incorrectly.

fix

Run npm install --save-dev vite-plugin-tsc-build. If using TypeScript, ensure your tsconfig includes node_modules types.

Warnings

gotcha The plugin only runs during build (when enabled) and does not affect the dev server. Development continues to use esbuild. ↓

fix Ensure that enabled is set to false or conditionally disabled in dev mode (e.g., enabled: mode === 'production').

gotcha The plugin expects a valid tsc command available in PATH. If tsc is not installed globally, the build may fail. ↓

fix Install TypeScript as a dev dependency (npm install --save-dev typescript) and ensure it is in node_modules/.bin.

gotcha The plugin runs tsc -b (project build mode) by default. If your project does not have a tsconfig.json with references configured, the build may fail with 'Solution-style project' errors. ↓

fix Either configure tsconfig.json with references or override the tsc arguments to '--noEmit' or a simple compilation command like ['--outDir', 'dist'].

breaking Version 0.3.0 dropped support for Vite 3. Projects on Vite 3 must pin to 0.2.x or upgrade Vite. ↓

fix Update Vite to ^4.0.0, ^5.0.0, ^6.0.0, or ^7.0.0, or stay on vite-plugin-tsc-build@0.2.x.

Install

npm install vite-plugin-tsc-build

yarn add vite-plugin-tsc-build

pnpm add vite-plugin-tsc-build

Imports

tscBuildPlugin (default)

wrong

const tscBuildPlugin = require('vite-plugin-tsc-build')

correct

import tscBuildPlugin from 'vite-plugin-tsc-build'

ESM-only; this package ships as ESM and does not export a CommonJS version.

tscBuildPlugin (named)
wrong
```
import tscBuildPlugin from 'vite-plugin-tsc-build'
```
correct
```
import { tscBuildPlugin } from 'vite-plugin-tsc-build'
```
Both default and named exports are available, but the named export avoids confusion with default import. Use whichever your project prefers.

Vite configuration

wrong

plugins: [tscBuildPlugin]

correct

import { defineConfig } from 'vite';
import tscBuildPlugin from 'vite-plugin-tsc-build';

export default defineConfig({
  plugins: [tscBuildPlugin({ enabled: true })]
});

The plugin must be instantiated with options; omitting the parentheses will cause a runtime error.

Quickstart

Configures the plugin to run tsc -b only during production builds, preserving Vite's fast esbuild dev mode.

// Install: npm install --save-dev vite-plugin-tsc-build typescript
// vite.config.ts
import { defineConfig } from 'vite';
import tscBuildPlugin from 'vite-plugin-tsc-build';

export default defineConfig(({ mode }) => ({
  plugins: [
    tscBuildPlugin({
      enabled: mode === 'production',
      // Optionally override tsc command line arguments:
      // tsc: ['-b', '--pretty']
    })
  ]
}));