esbuild-plugin-decorators

0.0.3 verified Fri May 01 auth: no javascript maintenance

esbuild-plugin-decorators (v0.0.3) is an esbuild plugin that enables support for experimental ECMAScript decorators. It patches the esbuild build process to transform decorators using the TypeScript compiler API. This plugin is intended for projects that rely on legacy decorator syntax (e.g., from TypeScript's experimentalDecorators or Babel) and need to bundle with esbuild, which does not natively support decorators. The plugin is minimal and has no dependencies beyond esbuild and TypeScript. However, it is experimental and not actively maintained; the latest version (0.0.3) was released in early 2023. Compared to alternatives like esbuild-plugin-babel or esbuild-plugin-typescript-decorators, this one is a lightweight wrapper but lacks comprehensive error handling and documentation. Use with caution in production.

Common errors

error Error: Cannot find module 'esbuild-plugin-decorators' ↓

cause Package not installed

fix

npm install esbuild-plugin-decorators

error Error: Decorators are not enabled. Set 'experimentalDecorators': true in tsconfig.json ↓

cause TypeScript decorator option not enabled

fix

Add "experimentalDecorators": true to tsconfig.json compilerOptions

error TypeError: decoratorsPlugin is not a function ↓

cause Imported default incorrectly (e.g., destructured as named export)

fix

Use import decoratorsPlugin from 'esbuild-plugin-decorators' (default import)

error Plugin error: esbuild version mismatch ↓

cause Incompatible esbuild version (plugin requires esbuild >=0.10)

fix

Update esbuild to version >=0.10 with npm update esbuild

Warnings

gotcha Plugin requires esbuild to be installed as a peer dependency. Not auto-installed. ↓

fix Install esbuild: npm install esbuild

gotcha Plugin requires TypeScript compiler API (typescript package) for transformation. Ensure tsconfig has experimentalDecorators: true. ↓

fix Install typescript: npm install typescript; set experimentalDecorators in tsconfig.json

deprecated The plugin is currently at version 0.0.3 with no updates since 2023. It may not work with newer esbuild versions. ↓

fix Consider using esbuild-plugin-babel or esbuild-plugin-typescript-decorators as more maintained alternatives.

gotcha The plugin does not handle source maps properly; decorator-transformed code may have incorrect source mappings. ↓

fix If source maps are important, consider a plugin that integrates Babel instead.

gotcha Only works with ES modules (import/export). Does not support CommonJS modules for the input files. ↓

fix Ensure your entry points use ES module syntax.

Install

npm install esbuild-plugin-decorators

yarn add esbuild-plugin-decorators

pnpm add esbuild-plugin-decorators

Imports

default

wrong

const decoratorsPlugin = require('esbuild-plugin-decorators')

correct

import decoratorsPlugin from 'esbuild-plugin-decorators'

Package exports a default function. ESM or CJS both work but default import is cleanest.

decoratorsPlugin

wrong

import { decoratorsPlugin } from 'esbuild-plugin-decorators'

correct

import decoratorsPlugin from 'esbuild-plugin-decorators'

Symbol is default export, not named.

apply decorators

wrong

esbuild.build({ plugins: [decoratorsPlugin] })

correct

esbuild.build({ plugins: [decoratorsPlugin()] })

Must call the function to create plugin instance.

Quickstart

Shows how to bundle TypeScript with experimental decorators using esbuild and the plugin.

import esbuild from 'esbuild';
import decoratorsPlugin from 'esbuild-plugin-decorators';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  outfile: 'dist/bundle.js',
  bundle: true,
  plugins: [decoratorsPlugin()],
  tsconfig: './tsconfig.json', // ensure experimentalDecorators: true
});