esbuild-tsc

1.2.0 verified Fri May 01 auth: no javascript

esbuild-tsc is an ESBuild plugin that uses the TypeScript compiler (tsc) to transpile TypeScript files, specifically enabling support for TypeScript decorators which ESBuild does not natively handle. Current stable version is 1.2.0, with updates following bug fixes and minor improvements. It is typically released on demand. Key differentiator: unlike other plugins that use Babel or SWC for TypeScript decorators, this leverages tsc directly, ensuring full compatibility with TypeScript's own decorator implementation and strict type checking. Requires Node >=16, peer dependency on typescript and esbuild.

Common errors

error Error: Cannot find module 'typescript' ↓

cause typescript is not installed as a peer dependency

fix

npm install --save-dev typescript

error TypeError: esbuildPluginTsc is not a function ↓

cause Incorrect import: using named import instead of default import

fix

import esbuildPluginTsc from 'esbuild-tsc'

error Error: tsconfig.json not found ↓

cause Options.tsconfigPath is not set or file path is incorrect

fix

Provide absolute path to tsconfig.json or ensure it exists in the working directory.

Warnings

breaking Package requires Node >=16, esbuild >=0.12, and typescript >=4.0. Older versions will fail to install or run. ↓

fix Update Node, esbuild, and typescript to minimum required versions.

gotcha The plugin overrides esbuild's default TypeScript handling for files matching the filter. If plugin is not applied, TypeScript decorators will be ignored or cause errors. ↓

fix Ensure the plugin is added to the plugins array and the filter covers your files (default: all .ts files).

deprecated Options.filter is deprecated in favor of include/exclude in tsconfig.json. Still works but may be removed in future major versions. ↓

fix Use tsconfig.json's include/exclude patterns instead of filter.

gotcha The plugin runs tsc synchronously per file, which can slow down builds significantly, especially on large codebases. ↓

fix Use only on files that require tsc (e.g., with decorators). Consider using esbuild's native TS for other files.

Install

npm install esbuild-tsc

yarn add esbuild-tsc

pnpm add esbuild-tsc

Imports

default

wrong

const esbuildPluginTsc = require('esbuild-tsc')

correct

import esbuildPluginTsc from 'esbuild-tsc'

ESM-only; uses default export. Not available via CommonJS require.

esbuildPluginTsc

wrong

import { esbuildPluginTsc } from 'esbuild-tsc'

correct

import esbuildPluginTsc from 'esbuild-tsc'

Named import is incorrect; the package exports a default function.

PluginOptions
wrong
```
import { PluginOptions } from 'esbuild-tsc'
```
correct
```
import type { PluginOptions } from 'esbuild-tsc'
```
PluginOptions is a type export, only available via type import in TypeScript.

Quickstart

Shows how to configure esbuild with esbuild-tsc plugin to compile TypeScript files supporting decorators.

import esbuild from 'esbuild';
import esbuildPluginTsc from 'esbuild-tsc';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    esbuildPluginTsc({
      tsconfigPath: './tsconfig.json',
      filter: /\\.ts$/
    })
  ]
});
console.log('Build complete');