esbuild-plugin-emit-decorator-metadata

0.2.3 verified Fri May 01 auth: no javascript

An esbuild plugin that enables TypeScript's `emitDecoratorMetadata` option for decorators, generating metadata for `reflect-metadata`. Current version 0.2.3 requires esbuild ^0.14.29 to ^0.25.0. It rewrites and improves upon the original esbuild-decorators package, fixing broken source maps and adding worker-thread support for parallel transpilation. Supports both ESM and CommonJS, ships TypeScript types. Key differentiators: correct source map handling, optional workers for performance, and support for `.tsx` files. Best alternative to using `tsc` for decorator metadata in esbuild.

Common errors

error Error: Cannot find module 'esbuild-plugin-emit-decorator-metadata' ↓

cause The package is not installed or not in the current project's dependencies.

fix

npm install -D esbuild-plugin-emit-decorator-metadata

error TypeError: esbuildEmitDecoratorMetadata is not a function ↓

cause Incorrect import style (e.g., default import instead of named import).

fix

Use named import: import { esbuildEmitDecoratorMetadata } from 'esbuild-plugin-emit-decorator-metadata'

error Error: tsconfig file not found at /path/to/tsconfig.json ↓

cause The `tsconfig` option path is incorrect or file does not exist.

fix

Ensure tsconfig path is absolute and valid: esbuildEmitDecoratorMetadata({ tsconfig: resolve(__dirname, 'tsconfig.json') })

error Error: Decorator metadata emission is only supported when 'experimentalDecorators' and 'emitDecoratorMetadata' are enabled in tsconfig ↓

cause The tsconfig.json does not have these options enabled.

fix

Add to tsconfig.json: { "compilerOptions": { "experimentalDecorators": true, "emitDecoratorMetadata": true } }

Warnings

gotcha Using `esbuildEmitDecoratorMetadata` will significantly slow down builds because each file is transpiled by TypeScript separately. For large projects, consider using workers or incremental builds. ↓

fix Enable workers option: `workers: 'auto'` or `workers: true`. Also ensure `tsconfig` path is correct to avoid repeated resolution.

gotcha The plugin does not support `.tsx` files by default; you must pass `tsx: true` in options. ↓

fix Add `tsx: true` to the plugin options: `{ tsconfig: '...', tsx: true }`.

deprecated The `force` option (transpile all `.ts` files) may be deprecated in future versions because it ignores esbuild's caching. ↓

fix Use it only for debugging; prefer letting esbuild handle caching.

gotcha Source maps may be incorrect if `sourceRoot` is not set correctly. The plugin expects `sourceRoot` to be absolute path to source directory. ↓

fix Set `sourceRoot: resolve(process.cwd(), 'src')` in esbuild config.

breaking Version 0.2.0 changed the internal worker pool behavior: previously default was no workers, now default is `workers: 'auto'`. ↓

fix If you want to disable workers, explicitly set `workers: false`.

Install

npm install esbuild-plugin-emit-decorator-metadata

yarn add esbuild-plugin-emit-decorator-metadata

pnpm add esbuild-plugin-emit-decorator-metadata

Imports

esbuildEmitDecoratorMetadata

wrong

const esbuildEmitDecoratorMetadata = require('esbuild-plugin-emit-decorator-metadata')

correct

import { esbuildEmitDecoratorMetadata } from 'esbuild-plugin-emit-decorator-metadata'

The package exports both ESM and CJS; named import works in both environments.

esbuildEmitDecoratorMetadata

wrong

const plugin = require('esbuild-plugin-emit-decorator-metadata').default

correct

const { esbuildEmitDecoratorMetadata } = require('esbuild-plugin-emit-decorator-metadata')

CJS users must destructure; default export does not exist.

PluginOptions

wrong

import { PluginOptions } from 'esbuild-plugin-emit-decorator-metadata'

correct

import type { esbuildEmitDecoratorMetadata } from 'esbuild-plugin-emit-decorator-metadata'

PluginOptions is not exported; only the function is exported. Use ReturnType<typeof esbuildEmitDecoratorMetadata> or inline type.

Quickstart

Shows basic esbuild build configuration using the plugin with automatic worker threads.

import { esbuildEmitDecoratorMetadata } from 'esbuild-plugin-emit-decorator-metadata';
import { resolve } from 'node:path';
import esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['./src/index.ts'],
  outfile: './dist/bundle.js',
  bundle: true,
  platform: 'node',
  tsconfig: resolve('tsconfig.json'),
  plugins: [
    esbuildEmitDecoratorMetadata({
      tsconfig: resolve('tsconfig.json'),
      workers: 'auto',
    }),
  ],
});
console.log('Build complete');