esbuild-plugin-decorator

0.4.0 verified Mon Apr 27 auth: no javascript

An ESBuild plugin that enables TypeScript decorator support during bundling. Version 0.4.0 compiles decorators using SWC under the hood, preserving semantics while maintaining fast build speeds. It integrates as an esbuild plugin with no config changes beyond registration. Key differentiators: leverages SWC's stable decorator transform, supports both legacy and TC39 stage 3 decorators, and works alongside other ESBuild plugins. Updated irregularly.

Common errors

error Error: Cannot find module '@swc/core' ↓

cause Missing peer dependency @swc/core.

fix

Run: npm install @swc/core

error Error: The decorator plugin only supports one decorator version per build ↓

cause Passing multiple decoratorVersion values or conflicting config.

fix

Ensure decoratorVersion is a single string: 'legacy' or 'tc39'.

error TypeError: esbuildPluginDecorator is not a function ↓

cause Importing a named export instead of default.

fix

Use: import esbuildPluginDecorator from 'esbuild-plugin-decorator'

Warnings

gotcha The plugin requires @swc/core to be installed as a peer dependency. Missing it causes a runtime error when decorators are encountered. ↓

fix Install @swc/core alongside this plugin: npm install @swc/core

gotcha The plugin does not handle export default class with decorators correctly; the decorator may not be applied properly in some edge cases. ↓

fix Avoid using export default class with decorators; use named exports instead.

deprecated The decoratorVersion option defaults to 'legacy' which is deprecated in TypeScript 5.0+. Users should migrate to 'tc39' for future compatibility. ↓

fix Set decoratorVersion: 'tc39' in plugin options.

gotcha If your tsconfig.json has 'useDefineForClassFields' set to false, the plugin may produce incorrect output. It assumes true. ↓

fix Set useDefineForClassFields: true in tsconfig.json.

Install

npm install esbuild-plugin-decorator

yarn add esbuild-plugin-decorator

pnpm add esbuild-plugin-decorator

Imports

esbuildPluginDecorator

wrong

const { esbuildPluginDecorator } = require('esbuild-plugin-decorator')

correct

import esbuildPluginDecorator from 'esbuild-plugin-decorator'

Default export only. ESBuild plugins are often loaded via ESM default import.

default
```
import decoratorPlugin from 'esbuild-plugin-decorator'
```
The package has a default export. Name your import anything you like.
EsbuildPluginDecoratorOptions
```
import type { EsbuildPluginDecoratorOptions } from 'esbuild-plugin-decorator'
```
Type import for configuration options. Exported as a named type.

Quickstart

Shows how to register the decorator plugin with esbuild, specifying the tsconfig path and decorator version (legacy for TypeScript <5.0, tc39 for modern).

import esbuild from 'esbuild';
import esbuildPluginDecorator from 'esbuild-plugin-decorator';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    esbuildPluginDecorator({
      tsconfig: './tsconfig.json',
      decoratorVersion: 'legacy', // 'legacy' | 'tc39'
    }),
  ],
});