TypeScript decorators can look similar while following different runtime rules. This guide helps you identify whether a project uses standard decorators or legacy experimentalDecorators, compare their capabilities, and migrate safely by checking compiler output, metadata, framework support, tests, and observable behavior.
Overview
A decorator is syntax attached to a class or class member that lets code observe, replace, or initialize that declaration. The important distinction is not the @name syntax; it is the decorator model used by the compiler and the libraries around it.
Modern TypeScript supports the current ECMAScript decorator model. It is enabled by using decorator syntax without relying on experimentalDecorators. TypeScript also supports the older, widely adopted model controlled by experimentalDecorators. These models have different function signatures, initialization behavior, supported targets, and metadata capabilities.
| Model or use case | How to recognize it | Important checks |
|---|---|---|
| Standard decorators | Decorators receive a value and a context object such as kind, name, access, and addInitializer. | Check the TypeScript version, output target, runtime support, and whether the library expects standard signatures. |
| Legacy decorators | The project uses experimentalDecorators: true; decorators commonly receive a target, property key, descriptor, or parameter index. | Preserve legacy signatures and test emitted behavior before changing compiler options. |
| Metadata-dependent frameworks | Dependency injection or reflection code reads design-time type metadata at runtime. | Standard decorators do not provide the same legacy metadata pipeline. Verify framework guidance and replacement registration patterns. |
| Decorator-based libraries | A package supplies decorators for routing, validation, serialization, ORM mappings, or commands. | Confirm the package's supported model instead of assuming that a compiler upgrade is a drop-in change. |
Do not treat a successful compilation as proof that a migration worked. A decorator can compile and still stop registering routes, alter initialization order, lose metadata, or change the value passed to a method. Runtime tests are part of the migration.
Checklist by scenario
Starting a new TypeScript project
- Choose the standard decorator model unless a required dependency explicitly needs the legacy model.
- Confirm that your supported JavaScript runtimes and bundler preserve the generated class behavior you need.
- Keep decorators focused on a clear concern, such as logging, registration, or initialization.
- Add a test for each decorator contract before using it across a large codebase.
A standard method decorator receives the original method and a context object. It can return a replacement method:
function logged<This, Args extends unknown[], Return>(
method: (this: This, ...args: Args) => Return,
context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
) {
const name = String(context.name);
return function (this: This, ...args: Args): Return {
console.log(`calling ${name}`);
return method.call(this, ...args);
};
}
class ReportService {
@logged
buildReport(format: string) {
return `report:${format}`;
}
}
The decorator above uses the standard value-and-context shape. It does not use a property descriptor, and it does not need experimentalDecorators.
Maintaining a legacy decorator project
- Locate
experimentalDecoratorsin every relevant tsconfig, including package and test configurations. - Search for decorator functions that accept
target,propertyKey,descriptor, or a parameter index. - Check for
emitDecoratorMetadataand imports from reflection libraries. - Lock down behavior with integration tests before changing the model.
function legacyLogged(
target: object,
propertyKey: string,
descriptor: PropertyDescriptor
) {
const original = descriptor.value;
descriptor.value = function (...args: unknown[]) {
console.log(`calling ${propertyKey}`);
return original.apply(this, args);
};
}
This is a legacy decorator shape. Passing it to a standard-decorator configuration is not a mechanical upgrade; the arguments and replacement rules are different.
Decorating fields, accessors, and classes
Standard decorators distinguish between fields and methods. A field decorator can return an initializer that transforms the initial value:
function trimField(value: unknown, context: ClassFieldDecoratorContext) {
if (context.kind !== "field") return;
return function (initialValue: unknown) {
return typeof initialValue === "string" ? initialValue.trim() : initialValue;
};
}
class User {
@trimField
displayName = " Ada ";
}
For accessor decorators, use the context and value shape required by the standard decorator API, and test both reads and writes. Class decorators can return a replacement class or register work with addInitializer. A replacement must preserve the constructor contract expected by callers.
Using dependency injection or runtime metadata
- List every place where a container discovers classes, tokens, constructor parameters, or providers.
- Determine whether discovery comes from explicit tokens, decorator side effects, or emitted design metadata.
- Do not assume standard decorators reproduce legacy parameter decorators or
emitDecoratorMetadata. - Prefer explicit registration when a framework's standard-decorator support is incomplete or changing.
For data entering a decorated class, runtime validation remains separate from compile-time decoration. A useful companion is TypeScript Runtime Validation: Zod, Valibot, and Standard Schema.
What to double-check before migration
- Compiler configuration: Compare the root, production, test, and package-specific tsconfig files. Check
experimentalDecorators,emitDecoratorMetadata,target,module, and any build tool that invokes a separate transpiler. - Decorator signatures: Classify each decorator as standard or legacy. A function receiving a context object is not interchangeable with one receiving a prototype and property descriptor.
- Supported targets: Record whether decorators are applied to classes, methods, fields, accessors, or constructor parameters. Standard and legacy models do not offer identical support for every target.
- Initialization order: Test static fields, instance fields, superclass construction, subclass construction, and decorator initializers. Logging alone may miss ordering changes.
- Generated JavaScript: Compile a small fixture with the old and new configurations. Review the output and run it in the actual test or application runtime rather than relying only on type-checking.
- Metadata and reflection: Search for calls that read design types or property metadata. If a container depends on those calls, verify an explicit migration path before changing flags.
- Exports and package consumers: If decorators are published from a package, test both the package's declarations and its emitted JavaScript. See the TypeScript package publishing checklist for related ESM, CommonJS, and declaration checks.
- Tests: Cover the observable contract: registration, replacement, method arguments, field values, thrown errors, metadata lookup, and construction order.
Common mistakes
- Changing only one flag: Removing
experimentalDecoratorsdoes not convert existing functions to standard decorators. Rewrite signatures and review each call site. - Assuming metadata is automatic: Standard decorator syntax should not be treated as a replacement for legacy emitted design metadata. Use explicit tokens or a framework-supported mechanism when needed.
- Using a method recipe on a field: Fields, methods, accessors, and classes have different values and initialization behavior. Check
context.kindand type the decorator for its intended target. - Returning the wrong replacement: A method decorator should return a compatible function; a field decorator returns an initializer when appropriate. An incompatible replacement can pass compilation only when types are too broad.
- Testing only TypeScript: Decorators execute at runtime. Add tests that import the built output or run through the same transpilation path used in production.
- Mixing toolchains silently: A TypeScript compiler, a test transformer, a bundler, and a framework build may not apply the same decorator settings. Make their configurations explicit.
If a decorator migration exposes unrelated type issues, isolate the change in a small fixture first. This keeps compiler errors separate from runtime registration failures and makes the resulting review easier to verify.
When to revisit
Revisit this checklist before upgrading TypeScript, a framework, a dependency-injection container, a routing or ORM library, or the project's JavaScript target. Also review it when changing bundlers, test runners, package module formats, or any compiler configuration shared by application and test builds.
At each review, record four decisions in the repository:
- Which decorator model the project uses.
- Which compiler and build configurations apply it.
- Whether runtime metadata is required and how it is supplied.
- Which tests prove registration, initialization, replacement, and production behavior.
Then compile a minimal decorator fixture, run the full integration suite, and inspect the built artifact used by deployment. If the project publishes decorated classes, repeat the check from a consumer package. This short routine turns a potentially subtle decorator change into a reviewable, repeatable migration rather than a compiler-option experiment.