TypeScript Decorators
TypeScript decorators are special functions that attach extra behavior or metadata to classes, methods, properties, or parameters. You write them with an @ symbol before the target. They are used heavily in frameworks like Angular and NestJS for dependency injection, routing, and validation. Understanding them helps you read framework code and build reusable patterns.
This tutorial covers what decorators are, the two flavours (the standard ECMAScript decorators from TypeScript 5.0 and the legacy experimentalDecorators used by older frameworks), class, method, and property decorators, decorator factories, and a logging method decorator. Each example clearly states which API it uses, because the signatures differ completely.
What Are TypeScript Decorators?
TypeScript decorators are functions that run when a class or class member is defined. They receive information about the target and can replace it, wrap it, or register metadata. The @ syntax is sugar for calling the decorator function with the target as an argument.
Here is a simple standard method decorator:
function logged<This, Args extends unknown[], Return>(
target: (this: This, ...args: Args) => Return,
context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
): (this: This, ...args: Args) => Return {
const name = String(context.name);
return function (this: This, ...args: Args): Return {
console.log(`Calling ${name}`);
return target.call(this, ...args);
};
}
class Greeter {
@logged
greet(name: string): string {
return `Hello, ${name}`;
}
}
console.log(new Greeter().greet("Riya"));
// Output: Calling greet
// Output: Hello, Riya
This example uses the standard decorator API from TypeScript 5.0. The decorator receives the original method and a context object, and returns a new function that wraps it .
What Are the Two Flavours of TypeScript Decorators?
TypeScript supports two decorator systems. The standard (ECMAScript) decorators shipped in TypeScript 5.0 and need no compiler flag. The legacy experimentalDecorators use an older Stage 2 proposal and require "experimentalDecorators": true in tsconfig.json. The two have completely different signatures, so you must know which one you are using .
// tsconfig.json for LEGACY decorators only
{
"compilerOptions": {
"target": "ES2022",
"experimentalDecorators": true,
"emitDecoratorMetadata": true
}
}
How it works: Without the flag, TypeScript uses the standard decorators. With the flag, it uses the legacy API. You cannot mix them in one class. The standard API has typed parameters and returns values explicitly. The legacy API uses any-typed parameters and mutates descriptors .
How Do You Write a Standard Method Decorator?
A method decorator wraps a class method. In the standard API, the decorator receives the method function as the first argument and a ClassMethodDecoratorContext as the second. It returns a replacement function. This is the signature used by modern tools like Lit and MobX .
function timed<This, Args extends unknown[], Return>(
target: (this: This, ...args: Args) => Return,
context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
): (this: This, ...args: Args) => Return {
return function (this: This, ...args: Args): Return {
const start = Date.now();
const result = target.call(this, ...args);
console.log(`${String(context.name)} took ${Date.now() - start}ms`);
return result;
};
}
class Calculator {
@timed
add(a: number, b: number): number {
return a + b;
}
}
console.log(new Calculator().add(2, 3));
// Output: add took 0ms
// Output: 5
How it works: The timed decorator returns a new function that records the start time, calls the original method with target.call(this, ...args), logs the duration, and returns the result. The context.name property gives the method name. The generic parameters preserve this, the argument types, and the return type, so no type information is lost .
How Does the Legacy Method Decorator Differ?
The legacy signature is (target, propertyKey, descriptor). You mutate descriptor.value or return a new descriptor. The parameters are often typed as any or Object, which loses type safety. This is the API used by NestJS, TypeORM, and older Angular versions .
// tsconfig.json: "experimentalDecorators": true
function loggedLegacy(target: object, propertyKey: string, descriptor: PropertyDescriptor) {
const original = descriptor.value;
descriptor.value = function (...args: unknown[]) {
console.log(`Calling ${propertyKey}`);
return original.apply(this, args);
};
}
class GreeterLegacy {
@loggedLegacy
greet(name: string): string {
return `Hello, ${name}`;
}
}
console.log(new GreeterLegacy().greet("Arjun"));
// Output: Calling greet
// Output: Hello, Arjun
How it works: The decorator receives the prototype (target), the method name (propertyKey), and the property descriptor. It saves the original function, replaces descriptor.value with a wrapper, and returns nothing. The mutation happens in place. Notice that args is unknown[], so the wrapper does not know the real parameter types .
How Do You Write a Decorator Factory?
A decorator factory is a function that returns a decorator. You use it when the decorator needs arguments, like a prefix string or a configuration object. You call the factory with @factory(options), and the returned function becomes the actual decorator.
function prefix(text: string) {
return function <This, Args extends unknown[], Return>(
target: (this: This, ...args: Args) => Return,
_context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
): (this: This, ...args: Args) => Return {
return function (this: This, ...args: Args): Return {
console.log(`${text}: ${String(args[0])}`);
return target.call(this, ...args);
};
};
}
class Service {
@prefix("INPUT")
process(value: string): string {
return value.toUpperCase();
}
}
console.log(new Service().process("hello"));
// Output: INPUT: hello
// Output: HELLO
How it works: prefix("INPUT") runs first and returns the actual decorator function. That function closes over text and uses it inside the wrapper. This pattern is how decorators accept configuration without losing access to the target and context .
What Are Class and Property Decorators?
A class decorator receives the class constructor and can return a replacement class. A property decorator runs when a field is defined. In the standard API, a field decorator receives undefined as the target and returns an initializer function .
function sealed<This, Args extends unknown[]>(
target: new (...args: Args) => object,
_context: ClassDecoratorContext
): void {
Object.seal(target);
Object.seal(target.prototype);
}
function readonlyField<This, Value>(
_target: undefined,
context: ClassFieldDecoratorContext<This, Value>
): (initialValue: Value) => Value {
return function (initialValue: Value): Value {
return initialValue;
};
}
@sealed
class Config {
@readonlyField
version = "1.0";
}
const c = new Config();
console.log(c.version);
// Output: 1.0
How it works: The sealed class decorator calls Object.seal on the constructor and prototype, preventing new properties from being added. The readonlyField property decorator returns an initializer that simply passes the value through. The @sealed syntax applies the decorator to the class, and @readonlyField applies it to the field .
How Do Decorators Work in Real Frameworks?
Decorators are the backbone of several major frameworks. Angular uses them for @Component, @Injectable, and @Input. NestJS uses @Controller, @Injectable, and parameter decorators for dependency injection. TypeORM uses @Entity, @Column, and @ManyToOne to map classes to database tables .
A crucial detail: NestJS, TypeORM, and older Angular rely on legacy decorators with experimentalDecorators and emitDecoratorMetadata. The standard decorators do not yet support parameter decorators, which these frameworks need for injection. If you work with these frameworks, you must keep the legacy flag on .
Standard vs Legacy Decorators: What Is the Difference?
| Feature | Standard (TS 5.0+) | Legacy (experimentalDecorators) |
|---|---|---|
| Compiler flag | None | "experimentalDecorators": true |
| Method signature | (value, context) |
(target, key, descriptor) |
| Typing | Fully typed generics | Often any |
| Return value | Returns replacement | Mutates descriptor |
| Parameter decorators | Not supported | Supported |
| Used by | Lit, MobX, Effect | NestJS, TypeORM, Angular |
The standard API is the future. The legacy API is still required for frameworks that depend on metadata reflection and parameter decorators. Check your framework before choosing .
Common Mistakes and Best Practices
- Mixing standard and legacy decorators in one class. The compiler uses one system based on the flag. Mixing produces confusing errors or silently wrong behavior. Pick one per project and stay consistent.
- Forgetting the legacy flag for framework code. If you copy a NestJS example into a project without
"experimentalDecorators": true, the decorator signature will not match and the build fails. Check the framework documentation for the required flags. - Losing types in the legacy signature. The legacy parameters are often typed as
anyorobject, so the wrapper loses argument types. Use the standard API for new code when possible, and add explicit generics where the legacy API allows. - Assuming decorators run at runtime in all builds. Some bundlers and compilers may not support decorators. Check your build tool's documentation. The standard decorators need a modern
targetsuch asES2022. - Using a decorator where a plain wrapper function would do. Decorators are syntax sugar for function composition. If you only need to wrap one call, a normal higher-order function is simpler and easier to test.
Real-World Example: A Logging Method Decorator
This example uses the standard TypeScript 5 decorator signature to build a logging decorator and applies it to a service class.
function logMethod<This, Args extends unknown[], Return>(
target: (this: This, ...args: Args) => Return,
context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
): (this: This, ...args: Args) => Return {
const methodName = String(context.name);
return function (this: This, ...args: Args): Return {
console.log(`[LOG] ${methodName} called with`, args);
const result = target.call(this, ...args);
console.log(`[LOG] ${methodName} returned`, result);
return result;
};
}
class UserService {
@logMethod
createUser(name: string, age: number): { id: number; name: string } {
return { id: 1, name };
}
}
const service = new UserService();
const user = service.createUser("Meera", 28);
console.log(user);
// Output:
// [LOG] createUser called with [ 'Meera', 28 ]
// [LOG] createUser returned { id: 1, name: 'Meera' }
// { id: 1, name: 'Meera' }
How it works, line by line. The logMethod decorator receives the original createUser function and a context object. It reads the method name from context.name. It returns a new function that logs the arguments before calling the original, then logs the result. The generics <This, Args, Return> preserve this, the argument tuple, and the return type, so the wrapper is fully typed. When service.createUser("Meera", 28) runs, the wrapper logs both the call and the return. The original method returns an object, and the wrapper passes it through unchanged. If you tried to call service.createUser(42, "x"), the compiler would still catch the type mismatch because the standard decorator does not erase the method's signature .
Summary
- TypeScript decorators attach behavior or metadata to classes and members using the
@syntax. - The standard decorators from TypeScript 5.0 use
(value, context)and need no compiler flag. - The legacy
experimentalDecoratorsuse(target, key, descriptor)and are required by NestJS, TypeORM, and older Angular. - Method decorators wrap functions; class decorators can replace or seal the class; property decorators can customize initialization.
- Decorator factories return a decorator and let you pass arguments like a prefix or options.
- Always check which API your framework expects, because the signatures are not interchangeable.
Now that you understand decorators, continue to the TypeScript with React tutorial to learn how to type components, props, and hooks in a real UI framework.
Frequently Asked Questions
Do I need experimentalDecorators in TypeScript 5?
Only if you use the legacy decorator API. Standard decorators from TypeScript 5.0 work without the flag. If you are starting a new project with no framework constraints, use the standard API and leave the flag off. If you use NestJS, TypeORM, or older Angular, you need the legacy flag.
Can I use standard decorators with NestJS?
Not yet in a full way. NestJS relies on parameter decorators and emitDecoratorMetadata, which the standard API does not support. The framework expects the legacy signature. Check the NestJS documentation for the current state before migrating, and keep experimentalDecorators on until they announce support.
What is a decorator factory in simple terms?
A decorator factory is a function that returns a decorator. You use it when your decorator needs arguments. Write function prefix(text) { return function(target, context) { ... } } and apply it as @prefix("LOG"). The outer function captures the argument, and the inner function is the actual decorator.
Why does my method decorator lose type information?
In the legacy API, the decorator parameters are often typed as any or object, so the compiler cannot track the method's argument and return types. The standard API uses generics like <This, Args, Return> to preserve those types. If you need type safety in the wrapper, use the standard API or add explicit generics where possible.
Can decorators be used on standalone functions?
No. TypeScript decorators only apply to classes and class members: the class itself, methods, properties, accessors, and (in the legacy API) parameters. You cannot put @logged on a plain function declaration. If you need to wrap a standalone function, use a higher-order function instead.
Practice Exercises
Exercise 1 (Easy): Standard Method Decorator
Write a standard method decorator logStart that prints Starting <methodName> before calling the original method. Apply it to a class method.
Show solution
function logStart<This, Args extends unknown[], Return>(
target: (this: This, ...args: Args) => Return,
context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
): (this: This, ...args: Args) => Return {
return function (this: This, ...args: Args): Return {
console.log(`Starting ${String(context.name)}`);
return target.call(this, ...args);
};
}
class Task {
@logStart
run(): string {
return "done";
}
}
console.log(new Task().run());
// Output: Starting run
// Output: done
The standard decorator receives the method and context, then returns a wrapper that logs before calling the original.
Exercise 2 (Easy): Decorator Factory
Write a factory tag(prefix: string) that returns a standard method decorator printing [prefix] <methodName>. Apply it with @tag("AUDIT").
Show solution
function tag(prefix: string) {
return function <This, Args extends unknown[], Return>(
target: (this: This, ...args: Args) => Return,
context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
): (this: This, ...args: Args) => Return {
return function (this: This, ...args: Args): Return {
console.log(`[${prefix}] ${String(context.name)}`);
return target.call(this, ...args);
};
};
}
class Payment {
@tag("AUDIT")
process(): string {
return "charged";
}
}
console.log(new Payment().process());
// Output: [AUDIT] process
// Output: charged
The factory captures prefix and the returned decorator uses it in the wrapper, so the same decorator logic works with different labels.
Exercise 3 (Medium): Legacy Method Decorator
Write a legacy method decorator using experimentalDecorators that logs the method name and the first argument. Show the tsconfig flag needed.
Show solution
// tsconfig.json
{ "compilerOptions": { "target": "ES2022", "experimentalDecorators": true } }
function legacyLog(target: object, key: string, descriptor: PropertyDescriptor) {
const original = descriptor.value;
descriptor.value = function (arg: unknown) {
console.log(`${key} called with ${String(arg)}`);
return original.call(this, arg);
};
}
class LegacyService {
@legacyLog
greet(name: string): string {
return `Hi ${name}`;
}
}
console.log(new LegacyService().greet("Riya"));
// Output: greet called with Riya
// Output: Hi Riya
The legacy decorator mutates descriptor.value and requires the experimentalDecorators flag. It receives (target, key, descriptor) instead of (value, context).
Exercise 4 (Challenge): Class Decorator with Standard API
Write a standard class decorator withTimestamp that adds a createdAt property to the class prototype. Apply it to a class and print the property.
Show solution
function withTimestamp<T extends new (...args: any[]) => object>(
target: T,
_context: ClassDecoratorContext
): T {
(target.prototype as Record<string, unknown>).createdAt = new Date("2025-01-01");
return target;
}
@withTimestamp
class Report {
title = "Monthly";
}
const r = new Report();
console.log((r as unknown as Record<string, unknown>).createdAt instanceof Date);
// Output: true
The class decorator receives the constructor and context, adds a property to the prototype, and returns the same class. The standard API allows returning the class to keep the original type.
Written by Shaikh Abdul Shahid
A Full-Stack Developer with experience in PHP, Laravel, JavaScript, and React.
Founder of Online Learner, sharing practical knowledge and programming tutorials.
Building and maintaining real-world web applications since 2017.
Your Feedback
Help us improve by sharing your thoughts.
Online Learner helps developers master programming, database concepts, interview preparation, and real-world implementation through structured learning paths.
Quick Links
© 2023 - 2026 OnlineLearner.in | All Rights Reserved.
