How to fix Decorators are not valid on parameters unless 'emitDecoratorMetadata' is enabled in TypeScript

Open your tsconfig.json file and ensure both experimentalDecorators and emitDecoratorMetadata are enabled:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES2020",
    "module": "commonjs"
  }
}

Both flags are required:
- experimentalDecorators: Enables decorator syntax
- emitDecoratorMetadata: Emits type metadata for parameters

Save the file and restart your TypeScript server in your IDE (VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server").

Parameter decorators require the reflect-metadata polyfill to store and retrieve type information at runtime.

Install it as a dependency (not devDependency):

npm install reflect-metadata
# or
yarn add reflect-metadata
# or
pnpm add reflect-metadata

Then import it at the very top of your application entry file (usually main.ts, index.ts, or app.ts):

// main.ts - FIRST import, before anything else
import "reflect-metadata";

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

This polyfill must be loaded before any decorators are evaluated.

Ensure TypeScript is actually reading your tsconfig.json file:

# Check which config file TypeScript is using
npx tsc --showConfig

Common issues:

Wrong directory: Make sure you're running tsc from the directory containing tsconfig.json

Extends chain broken: If you use extends, verify the base config exists:

{
  "extends": "./tsconfig.base.json",  // Must exist
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Multiple configs in monorepo: Ensure the correct tsconfig is being used for your package:

# Compile with specific config
npx tsc -p packages/api/tsconfig.json

TypeScript 5.0 introduced standard ECMAScript decorators, which are NOT compatible with parameter decorators or emitDecoratorMetadata.

If you're using TypeScript 5.0+, you MUST use legacy decorators (experimentalDecorators) for parameter decorators to work:

{
  "compilerOptions": {
    "experimentalDecorators": true,  // REQUIRED for parameter decorators
    "emitDecoratorMetadata": true,
    "target": "ES2022"
  }
}

Important: Standard decorators (without experimentalDecorators) do NOT support:
- Parameter decorators at all
- emitDecoratorMetadata
- Design-time type reflection

If you need parameter decorators (for dependency injection), you must use legacy decorators.

Ensure your build tools respect tsconfig.json decorator settings:

For ts-node:

// tsconfig.json
{
  "ts-node": {
    "compilerOptions": {
      "experimentalDecorators": true,
      "emitDecoratorMetadata": true
    }
  }
}

Or use command line flags:

ts-node --experimental-decorators --emit-decorator-metadata src/main.ts

For webpack with ts-loader:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: "ts-loader",
        options: {
          compilerOptions: {
            experimentalDecorators: true,
            emitDecoratorMetadata: true,
          },
        },
      },
    ],
  },
};

For NestJS: The default NestJS tsconfig already includes these settings. If you customized it, restore them.

If you're using isolatedModules: true (common with Babel, esbuild, or SWC), you may encounter limitations with decorators.

Check your configuration:

{
  "compilerOptions": {
    "isolatedModules": true,  // Can cause issues
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Workaround options:

1. Use tsc for type checking, fast bundler for builds:

// tsconfig.build.json (for esbuild/swc)
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "isolatedModules": false  // Only for type checking
  }
}

2. Use SWC with decorator support:

// .swcrc
{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "decorators": true
    },
    "transform": {
      "legacyDecorator": true,
      "decoratorMetadata": true
    }
  }
}

Run type checking separately: npx tsc --noEmit