TypeScript Reference ยท tsconfig: Language, Modules and Emit Options
TypeScript experimentalDecorators option
Reference for experimentalDecorators: how the legacy decorator mode differs from standard decorators, parameter decorators, and when you still need the flag.
experimentalDecorators switches TypeScript to its original decorator design, created years before the JavaScript standard existed. Since TypeScript 5.0, decorators that follow the standard work without any flag. The flag is therefore only needed for code written for the old design: older versions of Angular, NestJS, TypeORM, MobX and similar libraries.
The two designs are not compatible. A legacy decorator receives (target, key, descriptor); a standard decorator receives (value, context). A given project uses one or the other, decided by this flag.
{ "compilerOptions": { "experimentalDecorators": true } }
Try it
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.
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
{ "compilerOptions": { "experimentalDecorators": true } }
| Part | Description |
|---|---|
| Value | true or false. Default: false (standard decorators). |
| Legacy method decorator | (target: object, key: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor | void |
| Legacy parameter decorator | (target: object, key: string | symbol | undefined, index: number) => void (only in legacy mode) |
| Standard decorator | (value, context) => replacement | void, where context has kind, name, addInitializer and more. |
Edge cases: standard decorators have no parameter decorators. A decorator written for one mode is a type error in the other, as the second example shows.
Usage notes
- New projects: leave it off. Standard decorators are on the JavaScript standards track and need no flag.
- Framework projects that rely on dependency injection by parameter decorators (
constructor(@Inject() svc: Service)) still need the flag, usually with emitDecoratorMetadata. - Cannot mix. One project, one mode. A library compiled in legacy mode cannot be consumed by code that uses standard decorators on the same classes.
- Field semantics. Legacy field decorators interact with useDefineForClassFields; older frameworks often expect
false. - No decorators on object literals or functions in either mode.
- Migration means rewriting every decorator to the
(value, context)shape and replacing parameter decorators with another injection mechanism.