TypeScript 5.x Decorators: A Practical Guide

TypeScript 5.x ships with the ECMAScript stage 3 decorator proposal—a fundamentally different specification from the experimental decorators you may remember. These decorators are standardized, more composable, and designed for modern JavaScript runtimes.

Old vs New Decorators

The old experimental decorators (enabled via experimentalDecorators) ran at runtime and could arbitrarily modify class behavior. They relied on TypeScript's own transpilation and could not be tree-shaken. The new standard decorators return new functions or objects from simple factory functions. This makes them compatible with standard JavaScript tooling, tree-shakable, and introspectable by IDEs.

Basic Syntax

function log(target: Function, context: ClassMethodDecoratorContext) {
  return function(this: any, ...args: any[]) {
    console.log(`${String(context.name)} called with`, args);
    return target.call(this, ...args);
  }
}

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

The context parameter provides metadata about the decorated member: its name, kind (method, getter, setter, field, class), whether it is private or static, and accessors for private fields.

Practical Use Cases

Method logging wraps methods to log inputs, outputs, and execution time—invaluable for debugging API handlers and expensive computations without modifying the original implementation.

Access control decorators inspect the context to determine whether a method should execute. Combine with dependency injection to check user permissions at the decoration level rather than inside each method.

Input validation on setters (kind: 'setter') validates values before they are stored, centralizing validation logic that would otherwise be duplicated across call sites.

Migration Strategy

Existing code using experimental decorators continues working with the experimentalDecorators flag. New projects should use the standard syntax. The two systems can coexist in the same project but not on the same class member—choose one per file.

Performance

Standard decorators execute once at class definition time, not on every instantiation. The wrapper functions add a single closure layer per decorator, which is negligible for all practical purposes.