Skip to content

Decorators in TypeScript

Use decorators to annotate and modify classes, methods, properties, and parameters.

What you'll learn

  • What decorators are and how to enable them experimentally
  • Class, method, property, and parameter decorators
  • Decorator factories for configurable decorators
  • Common use cases: logging, validation, and dependency injection

Concept

Enabling Decorators

Decorators are an experimental TypeScript feature (stage 3 in the TC39 process). Enable them with "experimentalDecorators": true in tsconfig.json. A decorator is a function prefixed with @ that is applied to a class, method, property, or parameter. Decorators run at class definition time and can observe, replace, or modify the target they are applied to.

The Four Decorator Types

Class decorators receive the constructor function and can replace it. Method decorators receive the target, method name, and descriptor, and can wrap or replace the method. Property decorators receive the target and property name. Parameter decorators receive the target, method name, and parameter index. Each type has a different signature and use case. Method decorators are the most common — used for logging, authorization, and caching.

Decorator Factories

A decorator factory is a function that returns a decorator. This lets you configure the decorator with arguments: @log("verbose") calls the factory with "verbose" to produce the actual decorator. Factories are how most real-world decorators work, from NestJS controllers (@Controller("/users")) to class-validator properties (@IsEmail()). The factory pattern makes decorators reusable and configurable.

Example

              // Enable: "experimentalDecorators": true in tsconfig.json

// Method decorator factory — logs method calls.
function log(prefix: string) {
  return function (
    target: any,
    propertyKey: string,
    descriptor: PropertyDescriptor
  ) {
    const original = descriptor.value;
    descriptor.value = function (...args: any[]) {
      console.log(`[${prefix}] ${propertyKey}(${args.join(", ")})`);
      return original.apply(this, args);
    };
  };
}

// Class decorator — marks a class as deprecated.
function deprecated(target: any) {
  console.log(`Warning: ${target.name} is deprecated`);
}

@deprecated
class Calculator {
  @log("MATH")
  add(a: number, b: number): number {
    return a + b;
  }

  @log("MATH")
  multiply(a: number, b: number): number {
    return a * b;
  }
}

const calc = new Calculator();
console.log(calc.add(2, 3));
console.log(calc.multiply(4, 5));
            

Decorators (enabled with experimentalDecorators) annotate classes, methods, properties, and parameters. Decorator factories return configurable decorators. They are widely used in frameworks like NestJS and TypeORM.

Try it

  • Code Diff

    Compare code with and without decorators to see the transformation.

  • Code Minifier

    Observe how decorators compile to JavaScript helper functions.

Common mistakes

The mistake

Using decorators without enabling experimentalDecorators in tsconfig

The fix

Decorators are experimental. Set "experimentalDecorators": true in tsconfig.json compilerOptions. Without it, the compiler reports a syntax error on the @ syntax.

The mistake

Confusing TypeScript decorators with the TC39 standard decorator proposal

The fix

TypeScript's experimental decorators are the legacy design. The TC39 standard (stage 3) has a different API. Check which version your framework expects before writing decorators.

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors