TypeScript Decorators Done Right: Migrating from Legacy to the TC39 Standard
Most decorator migration failures stem from treating TC39 standard decorators as a drop-in replacement for the legacy experimentalDecorators implementation. Teams flip the compiler flag, watch their codebase explode with type errors, and immediately revert. The reality is that the API changed fundamentally—parameter decorators disappeared, metadata handling shifted entirely, and the decorator signature itself operates on different principles.
This matters because TypeScript 5.0+ ships standard decorators by default, and the legacy implementation will eventually deprecate. Production codebases running experimentalDecorators: true face a migration debt that compounds with every new feature. The transition requires understanding what actually changed at the runtime level, not just syntax adjustments.
Key Takeaways
Legacy decorators and TC39 standard decorators use incompatible APIs—parameter decorators no longer exist, and metadata handling moved from reflect-metadata to context.metadata.
