esbuild-plugin-tsc

0.5.0 verified Mon Apr 27 auth: no javascript

An esbuild plugin that delegates TypeScript compilation to the official tsc compiler, enabling support for features not natively handled by esbuild, such as emitDecoratorMetadata, experimental decorators, and other TypeScript-only transforms. Version 0.5.0 supports TypeScript ^4.0.0 || ^5.0.0 and ships TypeScript type definitions. It targets projects that need tsc for specific files (e.g., those using decorators) while letting esbuild handle the rest, or can force tsc for all files via the `force` option. Released as needed, with a focus on bridging gaps between esbuild's fast but limited TS support and tsc's full feature set.

Common errors

error Error: Cannot find module 'typescript' ↓

cause typescript is not installed as a peer dependency.

fix

Run npm install --save-dev typescript

error TypeError: esbuildPluginTsc is not a function ↓

cause Used named import `{ esbuildPluginTsc }` instead of default import.

fix

Change to import esbuildPluginTsc from 'esbuild-plugin-tsc'

error error TS2349: This expression is not callable. Type 'typeof import("...")' has no call signatures. ↓

cause TypeScript error due to incorrect import style (CommonJS vs ESM) or missing type definitions.

fix

Use import esbuildPluginTsc from 'esbuild-plugin-tsc' and ensure esModuleInterop is enabled in tsconfig.json.

Warnings

gotcha This plugin runs tsc for files that match the filter, which is slower than esbuild's native TypeScript support. Do not use unless you need features esbuild cannot handle (e.g., emitDecoratorMetadata). ↓

fix Use esbuild's native TypeScript support for most projects; only apply this plugin on specific files via the esbuild plugin filter mechanism.

deprecated The `forceEsm` option may be removed in future versions as TypeScript's ESM handling evolves. ↓

fix Use TypeScript's module settings directly in tsconfig.json instead.

gotcha If you set `force: true`, all TypeScript files will be compiled by tsc, negating esbuild's speed advantage. Only enable for files that require tsc. ↓

fix Set `force: false` (default) and rely on esbuild's built-in handling for most files.

gotcha The plugin requires TypeScript as a peer dependency; if not installed, the build will fail at runtime. ↓

fix Install typescript: `npm install --save-dev typescript`

breaking Version 0.3.0 changed the default export from a named object to a function. Old import style (`import { esbuildPluginTsc }`) will not work. ↓

fix Update imports to use default import: `import esbuildPluginTsc from 'esbuild-plugin-tsc'`

Install

npm install esbuild-plugin-tsc

yarn add esbuild-plugin-tsc

pnpm add esbuild-plugin-tsc

Imports

default
wrong
```
const esbuildPluginTsc = require('esbuild-plugin-tsc')
```
correct
```
import esbuildPluginTsc from 'esbuild-plugin-tsc'
```
Package exports a default function; ESM import is recommended. CommonJS require works but may cause interop issues in TypeScript.
esbuildPluginTsc (as named import)
wrong
```
import { esbuildPluginTsc } from 'esbuild-plugin-tsc'
```
correct
```
import { default as esbuildPluginTsc } from 'esbuild-plugin-tsc'
```
There is no named export; only default export exists. Attempting named import will cause runtime undefined.
type Options
wrong
```
import { Options } from 'esbuild-plugin-tsc'
```
correct
```
import type { Options } from 'esbuild-plugin-tsc'
```
Options is a type-only export. Use import type to avoid emitting a value import. Only used in TypeScript code.

Quickstart

Configures esbuild with the plugin to compile TypeScript, optionally enabling JSX support via tsx option.

import esbuildPluginTsc from 'esbuild-plugin-tsc';
import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    esbuildPluginTsc({
      force: false,
      tsx: true
    })
  ],
});