Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Classes, Enums and Decorators

TypeScript experimentalDecorators option

Reference for the experimentalDecorators compiler option: legacy decorator signatures, emitDecoratorMetadata, parameter decorators and how they differ from standard decorators.

experimentalDecorators switches @decorator syntax back to the legacy implementation that TypeScript shipped before the standard was finished. Angular, NestJS, TypeORM and many older libraries still rely on it, so you will meet it in real projects.

Without the flag, TypeScript 5.0 and later compile decorators as the standard design, whose functions take (value, context). The two systems are not compatible: a decorator written for one fails to type-check under the other.

JSON
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Try it

TypeScript A legacy decorator in standard mode

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript The standard version of the same decorator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

This is a tsconfig.json option (read-only here; it cannot be set from inside one file).

Option Description
experimentalDecorators true enables legacy decorators. Default false.
emitDecoratorMetadata With the legacy mode, emits design:type, design:paramtypes and design:returntype through Reflect.metadata. Needs the reflect-metadata package.
Legacy decorator Receives
Class (constructor)
Method / accessor (target, propertyKey, descriptor)
Property (target, propertyKey)
Parameter (target, propertyKey, parameterIndex)

Usage notes

  • Parameter decorators (constructor(@Inject() dep: Dep)) exist only in the legacy system. Standard decorators have no parameter form.
  • Metadata for dependency injection comes from emitDecoratorMetadata; standard decorators offer context.metadata instead, which you fill yourself.
  • Legacy property decorators cannot change the field value directly; they usually define accessors on the prototype.
  • Under experimentalDecorators, the accessor keyword and the context-based types are not used.
  • The two systems cannot be mixed in one compilation. Choose the one your framework needs, and migrate whole projects at once.
  • Some tools (esbuild, SWC, Babel) need the same flag in their own configuration to emit legacy decorators.
  • New code should prefer standard decorators unless a framework forces the legacy mode.