Decorator Standardization Progress
You'll learn: How TypeScript decorators are transitioning from experimental to stage 3 ECMAScript standard, what breaks in the process, and how to migrate existing decorator code safely.
The Decorator Evolution Journey
TypeScript decorators have been in "experimental" limbo for years. When TypeScript first introduced them around version 1.5, they were based on an early TC39 proposal. The problem? That proposal kept changing, stalled at stage 2, and eventually was completely redesigned. Meanwhile, thousands of projects built on TypeScript's experimental version.
Now, with decorators reaching stage 3 in the TC39 process, TypeScript is shifting to support the standardized version. This is great for JavaScript alignment—but creates a painful migration path.
What Changed: The Breaking Differences
The stage 3 decorator proposal differs significantly from TypeScript's experimental version:
Key differences:
- Decorator execution order changed (top-to-bottom vs bottom-to-top in some contexts)
- Parameter decorators no longer exist in the standard
- Decorator context object is now the primary way to access metadata
- Return types and signatures have changed
- No implicit class field initialization modifications
Think of it like upgrading from an unofficial beta API to the final released version—the core idea stayed the same, but many details shifted.
The Migration Path
TypeScript 5.0+ supports stage 3 decorators when you disable the experimental flag. You'll need to:
- Remove or update
"experimentalDecorators": truefor new standard decorators - Rewrite decorators using the new context object patterns
- Replace parameter decorators with alternative approaches
- Test thoroughly—silent behavior changes are possible
Key Takeaway: TypeScript decorators are moving from experimental to standardized stage 3 syntax with breaking changes; migration requires careful rewriting of existing decorator code, but aligns TypeScript with the official JavaScript future.