Eight years. That’s how long the TC39 decorators proposal took to reach Stage 3.

It started in 2014 — ancient history in JavaScript years — went through multiple complete rewrites, and finally stabilized in March 2022. TypeScript 5.0 shipped last month with support for the standard version.

If you’ve been using --experimentalDecorators (and if you work with Angular, NestJS, or MobX, you almost certainly have), this matters. The new decorators aren’t a drop-in replacement. Not even close.

What Changed #

The standard ECMAScript decorators work differently from the experimental ones. No parameter decorators. No decorator metadata — that’s been split into a separate TC39 proposal that’s still in progress. The API surface for writing decorators? Completely redesigned.

For consumers, the syntax looks similar:

@logged
class MyService {
  @validate
  greet(name: string) {
    return `Hello, ${name}`;
  }
}

But under the hood, everything changed. Old experimental decorators received (target, propertyKey, descriptor). New standard decorators receive (value, context) where context carries the metadata. It’s a cleaner API, honestly — but it breaks every existing decorator library.

Every. Single. One.

The Migration Problem #

Here’s where it gets uncomfortable.

Angular’s entire component model is built on experimental decorators. So is NestJS. So is MobX’s observable system. Each of these frameworks now faces a choice: maintain backward compatibility forever, or ship a migration path that’ll take years to complete.

TypeScript 5.0 still supports --experimentalDecorators, so nothing breaks immediately. But the writing’s on the wall. Standard decorators are the future; the experimental flag is legacy now.

I worked adjacent to the Angular team at Google during my first stint there. The decorator situation was a constant source of tension — Angular bet heavily on a proposal that kept shifting underneath them. Parameter decorators didn’t make it into the standard (Angular uses them everywhere for dependency injection), which means their migration won’t be trivial. It’ll be a multi-year effort.

The Other Good Stuff #

Decorators get the headlines, but TypeScript 5.0 shipped other changes worth your attention.

const type parameters are quietly powerful. You can now write function foo<const T>(arr: T) and TypeScript preserves literal types without callers adding as const. Small syntax change, big ergonomic win for library authors.

The internal rewrite — moving from the module keyword to namespace — yielded 10-20% speed improvements in the compiler and a smaller npm package. That’s the kind of performance win that compounds across every CI pipeline running TypeScript.

What I’d Watch #

The gap between “standard decorators exist” and “the ecosystem has migrated” will be measured in years, not months. Libraries need to support both old and new decorators during the transition. Framework authors need to decide when to drop --experimentalDecorators support.

If you’re starting a new project today, use the standard decorators. If you’re maintaining code with experimental decorators, don’t panic — the flag isn’t going away tomorrow. But start planning. The longer you wait, the more code piles up on the legacy path.

And legacy code has a way of sticking around longer than you’d like.