TypeScript Decorators: Standard (TS 5+) vs. Legacy Explained

What are TypeScript decorators?

A decorator is a function you attach to a class or class member with @. It gets called when the class is defined and can replace, wrap, or initialize the thing it decorates. Typical uses: logging, validation, binding this, registering classes, or attaching metadata.

1
class Calculator {
2
  @logged
3
  add(a: number, b: number) {
4
    return a + b;
5
  }
6
}

TypeScript has two incompatible decorator implementations:

• Standard decorators (TypeScript 5.0+): follow the TC39 decorators proposal. They work without any compiler flag.
• Legacy decorators ("experimentalDecorators": true): TypeScript’s implementation of an old draft from 2015. This is what Angular, NestJS, TypeORM and InversifyJS are built on.

The experimentalDecorators flag decides which one you get for the whole project. If it is set, every decorator is a legacy decorator.

Standard decorators (TypeScript 5.0+)

A standard decorator has this shape:

1
type Decorator = (
2
  value: Input, // the decorated method, getter, setter, class, ... (undefined for fields)
3
  context: {
4
    kind: 'class' | 'method' | 'getter' | 'setter' | 'field' | 'accessor';
5
    name: string | symbol | undefined; // undefined only for anonymous classes
6
    static: boolean; // not on class decorators
7
    private: boolean; // not on class decorators
8
    access: {
9
      // not on class decorators; methods/getters have no set, setters no get
10
      has(object: This): boolean;
11
      get(object: This): Value;
12
      set(object: This, value: Value): void;
13
    };
14
    addInitializer(initializer: () => void): void;
15
    metadata: DecoratorMetadataObject; // TS 5.2+, typed `| undefined` if your lib lacks Symbol.metadata
16
  },
17
) => Output | void;

The decorator gets the original value plus a context object and can return a replacement of the same kind: a method for a method, a class for a class. It can’t turn a method into a field. TypeScript ships a typed context for every kind: ClassDecoratorContext, ClassMethodDecoratorContext, ClassGetterDecoratorContext, ClassSetterDecoratorContext, ClassFieldDecoratorContext and ClassAccessorDecoratorContext.

addInitializer() registers a function that runs once the decorated thing is set up: in the constructor for instance members, at class definition for static members and classes.

Method decorator: logging

1
function logged<This, Args extends unknown[], Return>(
2
  target: (this: This, ...args: Args) => Return,
3
  context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
4
) {
5
  const name = String(context.name);
6

7
  return function (this: This, ...args: Args): Return {
8
    console.log(`→ ${name}(${args.join(', ')})`);
9
    const result = target.call(this, ...args);
10
    console.log(`← ${name} returned ${result}`);
11
    return result;
12
  };
13
}
14

15
class Calculator {
16
  @logged
17
  add(a: number, b: number) {
18
    return a + b;
19
  }
20
}
21

22
new Calculator().add(1, 2);
23
// → add(1, 2)
24
// ← add returned 3

The generics look heavy, but they keep this, the arguments and the return type intact. If you don’t care, target: any, context: ClassMethodDecoratorContext works as well.

Class decorator

A class decorator receives the class itself. Here it uses addInitializer(), which runs after the class is fully defined (incl. static fields):

1
function sealed<Class extends abstract new (...args: any) => any>(target: Class, context: ClassDecoratorContext<Class>) {
2
  context.addInitializer(function () {
3
    Object.seal(this);
4
    Object.seal(this.prototype);
5
  });
6
}
7

8
@sealed
9
class Order {
10
  static currency = 'EUR';
11
}
12

13
// strict mode (ES modules, "use strict"): TypeError: Cannot add property discount, object is not extensible
14
// sloppy mode (plain scripts): silently ignored
15
(Order as any).discount = 10;

A class decorator may also return a new class (e.g. a subclass of target) to replace the original one. For a deeper dive into class decorators see the follow-up post below.

Field decorator: returns an initializer

Fields don’t exist yet when the decorator runs, so value is undefined. Instead, a field decorator can return a function that receives the initial value and returns the value the field actually gets:

1
function trimmed<This>(_value: undefined, context: ClassFieldDecoratorContext<This, string>) {
2
  return function (this: This, initialValue: string) {
3
    return initialValue.trim();
4
  };
5
}
6

7
class User {
8
  @trimmed name = '  Jannik  ';
9
}
10

11
const user = new User();
12
user.name; // 'Jannik'
13
user.name = '  Jannik  ';
14
user.name; // '  Jannik  ' – later assignments are not intercepted

Accessor decorator: intercept every read and write

To intercept later assignments, use the accessor keyword (an “auto-accessor”, available since TypeScript 4.9). It turns the field into a getter/setter pair backed by private storage. An accessor decorator can return new get, set and init functions. This one also is a decorator factory (see next section):

1
function min(limit: number) {
2
  return function <This>(
3
    target: ClassAccessorDecoratorTarget<This, number>,
4
    context: ClassAccessorDecoratorContext<This, number>,
5
  ): ClassAccessorDecoratorResult<This, number> {
6
    const check = (value: number) => {
7
      if (value < limit) throw new RangeError(`${String(context.name)} must be >= ${limit}, got ${value}`);
8
      return value;
9
    };
10

11
    return {
12
      init: check,
13
      set(value) {
14
        target.set.call(this, check(value));
15
      },
16
    };
17
  };
18
}
19

20
class Cart {
21
  @min(1) accessor quantity = 1;
22
}
23

24
const cart = new Cart();
25
cart.quantity = 3; // fine
26
cart.quantity = 0; // RangeError: quantity must be >= 1, got 0

Decorator factories

To pass options to a decorator, write a function that returns the decorator. That’s a decorator factory:

1
function log(prefix: string) {
2
  return function <This, Args extends unknown[], Return>(
3
    target: (this: This, ...args: Args) => Return,
4
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
5
  ) {
6
    return function (this: This, ...args: Args): Return {
7
      console.log(`${prefix} ${String(context.name)}`);
8
      return target.call(this, ...args);
9
    };
10
  };
11
}
12

13
class Api {
14
  @log('[api]')
15
  fetchOrders() {
16
    return [];
17
  }
18
}
19

20
new Api().fetchOrders(); // [api] fetchOrders

Decorator metadata (TypeScript 5.2+)

TypeScript 5.2 added context.metadata: one plain object shared by all decorators of a class and available afterwards as MyClass[Symbol.metadata]. That’s the standard replacement for reflect-metadata style annotations:

1
// runtimes don't ship Symbol.metadata yet, so polyfill it
2
(Symbol as { metadata?: symbol }).metadata ??= Symbol('Symbol.metadata');
3

4
function serializable(_value: undefined, context: ClassFieldDecoratorContext) {
5
  const fields = (context.metadata.serializable ??= []) as (string | symbol)[];
6
  fields.push(context.name);
7
}
8

9
class Invoice {
10
  @serializable id = 'inv-1';
11
  @serializable total = 42;
12
  internalNote = 'do not export';
13
}
14

15
Invoice[Symbol.metadata]?.serializable; // ['id', 'total']

You need "esnext" or "esnext.decorators" in your lib setting for the Symbol.metadata types.

Order of evaluation

1
function trace(label: string) {
2
  console.log(`evaluate ${label}`);
3
  return function (_target: unknown, context: DecoratorContext) {
4
    console.log(`apply ${label} to ${context.kind} ${String(context.name)}`);
5
  };
6
}
7

8
@trace('class')
9
class Demo {
10
  @trace('first')
11
  @trace('second')
12
  method() {}
13

14
  @trace('field')
15
  field = 1;
16
}
17

18
// evaluate class
19
// evaluate first
20
// evaluate second
21
// evaluate field
22
// apply second to method method
23
// apply first to method method
24
// apply field to field field
25
// apply class to class Demo

1. Decorator expressions (the factory calls) are evaluated top to bottom.
2. Stacked decorators are applied bottom-up: the one closest to the member wraps first.
3. The class decorator is applied after all member decorators.

What’s not in the standard

Parameter decorators (constructor(@Inject('DB') db: Db)) are not part of the TC39 proposal and TypeScript only supports them with experimentalDecorators. Same for emitDecoratorMetadata, which doesn’t work with standard decorators.

Legacy decorators (experimentalDecorators)

Before TypeScript 5.0, this was the only option. You enable it in tsconfig.json:

1
{
2
  "compilerOptions": {
3
    "experimentalDecorators": true,
4
    "emitDecoratorMetadata": true // optional, see below
5
  }
6
}

Legacy decorators get target (the prototype for instance members, the constructor for static members), propertyKey and, for methods and accessors, a property descriptor. The signatures in lib.decorators.legacy.d.ts:

1
declare type ClassDecorator = <TFunction extends Function>(target: TFunction) => TFunction | void;
2
declare type PropertyDecorator = (target: Object, propertyKey: string | symbol) => void;
3
// also used for accessors (getter/setter)
4
declare type MethodDecorator = <T>(
5
  target: Object,
6
  propertyKey: string | symbol,
7
  descriptor: TypedPropertyDescriptor<T>,
8
) => TypedPropertyDescriptor<T> | void;
9
declare type ParameterDecorator = (
10
  target: Object,
11
  propertyKey: string | symbol | undefined,
12
  parameterIndex: number,
13
) => void;

The logging decorator from above, legacy style:

1
function logged(target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) {
2
  const original = descriptor.value;
3
  descriptor.value = function (this: unknown, ...args: unknown[]) {
4
    console.log(`→ ${String(propertyKey)}`);
5
    return original.apply(this, args);
6
  };
7
}

Decorator factories and composition work the same way as with standard decorators: factories are evaluated top to bottom, decorators are applied bottom-up. Within a class, TypeScript applies instance member decorators first, then static member decorators, then constructor parameter decorators and finally the class decorator.

Why Angular, NestJS, TypeORM and InversifyJS still use it

The dependency injection of NestJS, TypeORM and InversifyJS relies on two things the standard doesn’t offer:

• Parameter decorators like constructor(@Inject(TOKEN) repo: Repo).
• emitDecoratorMetadata: TypeScript emits the design-time types (design:type, design:paramtypes, design:returntype) of decorated members, which the framework reads at runtime via reflect-metadata. That’s how NestJS knows which service to inject into a constructor without you naming it.

Angular is different: its compiler reads constructor parameter types from the source at build time, so it doesn’t need emitDecoratorMetadata. And with the inject() function, which Angular now prefers over constructor injection, you don’t need parameter decorators either.

Still, both nest new and ng new generate a tsconfig.json with "experimentalDecorators": true (only NestJS also sets emitDecoratorMetadata). If you use one of these frameworks, keep the flag. Don’t mix both styles in one project.

Standard vs. legacy decorators

For new code without such a framework: use standard decorators.

Runtime and tooling support (October 2026)

No JavaScript engine ships decorators natively. In May 2026, TC39 even moved the proposal back from Stage 3 to Stage 2.7 (decorator metadata as well), because after four years at Stage 3 no engine had shipped them. Stage 2.7 still means the committee expects decorators to become part of JavaScript, but details may change.

So you always need a compiler that transforms decorators into plain JavaScript:

• TypeScript (tsc) transforms both standard and legacy decorators. Standard decorators are transformed for every target below ESNext. With ESNext, they stay in the output as-is, which no runtime can execute today.
• TypeScript 7 (the native Go port, tsc from typescript@7) emits both styles, incl. emitDecoratorMetadata. Support landed in typescript-go#2343 (legacy) and typescript-go#2926 (standard).
• esbuild (and therefore tsx) supports standard decorators since 0.21.0 and legacy ones if experimentalDecorators is set in tsconfig.json. It does not support emitDecoratorMetadata, which is why NestJS projects usually stick to tsc or SWC.
• Babel: @babel/plugin-proposal-decorators with version: "2023-11" for standard decorators or version: "legacy".

Next: class decorators and dependency injection

In the follow-up post TypeScript class decorators incl. dependency injection example I build a small dependency injection container with class decorators. Note that it uses legacy decorators (experimentalDecorators), like NestJS and Angular do.

Resources

🔗 TypeScript 5.0 release notes: Decorators

🔗 TypeScript 5.2 release notes: Decorator Metadata

🔗 TypeScript Handbook: Decorators (legacy)

🔗 TC39 decorators proposal

🔗 TC39 decorator metadata proposal