esbuild-plugin-ts-decorators

1.0.3 verified Mon Apr 27 auth: no javascript

An esbuild plugin that enables TypeScript's emitDecoratorMetadata support by transpiling decorated files with the TypeScript compiler. Version 1.0.3 is the latest and only stable release. It provides a lightweight, regex-based decorator detection and optional caching. Unlike alternatives like ts-jest or tsc compilation, this plugin integrates directly with esbuild's fast bundler, only reverting to tsc for files that contain decorators when emitDecoratorMetadata is enabled. Best suited for projects that need both esbuild's speed and TypeScript decorators with metadata reflection (e.g., NestJS, TypeORM, inversify).

Common errors

error TypeError: Cannot read properties of undefined (reading 'fileName') ↓

cause The plugin expects a tsconfig path but it's not provided or the tsconfig is missing.

fix

Pass a valid tsconfig option: esbuildDecorators({ tsconfig: 'tsconfig.json' })

error Error: The plugin 'esbuild-plugin-ts-decorators' must be used after the 'ts' plugin? ↓

cause Order of plugins matters; the decorator plugin should come before other plugins that transform TypeScript.

fix

Ensure esbuildDecorators is the first plugin in the plugins array.

error Module not found: Can't resolve 'esbuild-plugin-ts-decorators' ↓

cause Package not installed or import path incorrect.

fix

Run npm install esbuild-plugin-ts-decorators --save-dev and verify the import statement: import { esbuildDecorators } from 'esbuild-plugin-ts-decorators'

Warnings

gotcha Plugin performance impact: all .ts files are processed by the plugin's regex to detect decorators, which adds overhead compared to plain esbuild builds. ↓

fix If performance is a concern, consider using alternative tools like tsc or ts-jest for decorator-heavy projects, or limit the plugin's scope with esbuild's plugin filters.

gotcha Cache behavior: when watch mode is off, cache defaults to false; you must set cache: true explicitly to enable caching. ↓

fix Set cache: true in plugin options if you want to avoid re-compiling unchanged decorated files on every build.

deprecated The plugin relies on an unstable regex pattern for decorator detection; future TypeScript decorator syntax changes may break matching. ↓

fix Stay updated with plugin releases; consider using a more robust parser (e.g., TypeScript's AST) if regex fails.

gotcha Not compatible with TypeScript's experimentalDecorators: false; plugin assumes experimental decorators are used. ↓

fix Ensure your tsconfig.json has "experimentalDecorators": true and "emitDecoratorMetadata": true.

gotcha The plugin only transpiles files that actually contain decorators; files without decorators are passed through esbuild as normal, so they won't have emitDecoratorMetadata. ↓

fix If a file uses decorators indirectly (e.g., re-exports), it may not be detected; manually include the file or set force: true to transpile all files.

Install

npm install esbuild-plugin-ts-decorators

yarn add esbuild-plugin-ts-decorators

pnpm add esbuild-plugin-ts-decorators

Imports

esbuildDecorators

wrong

const esbuildDecorators = require('esbuild-plugin-ts-decorators')

correct

import { esbuildDecorators } from 'esbuild-plugin-ts-decorators'

Package ships TypeScript types; default export not available; named export only.

esbuild
wrong
```
const { build } = require('esbuild')
```
correct
```
import { build } from 'esbuild'
```
esbuild is ESM-only starting from v0.12; CommonJS require may fail depending on module resolution.

Options

wrong

import { Options } from 'esbuild-plugin-ts-decorators'

correct

import type { Options } from 'esbuild-plugin-ts-decorators'

Options type is exported but used only for TypeScript types; no runtime value.

Quickstart

Shows how to set up esbuild with esbuild-plugin-ts-decorators, including plugin options and TypeScript type usage.

import { build } from 'esbuild';
import { esbuildDecorators } from 'esbuild-plugin-ts-decorators';

async function buildWithDecorators() {
  const result = await build({
    entryPoints: ['src/index.ts'],
    bundle: true,
    outfile: 'dist/index.js',
    platform: 'node',
    target: 'node14',
    tsconfig: 'tsconfig.json',
    plugins: [
      esbuildDecorators({
        tsconfig: 'tsconfig.json',
        cwd: process.cwd(),
        cache: true,
        tsx: false,
      }),
    ],
  });
  console.log('Build successful');
}

buildWithDecorators().catch(console.error);