Experimental Decorators in TypeScript: Under the Hood

Why Is Your TypeScript Screaming About "Experimental Decorators"?

Have you ever compiled a TypeScript project and seen something like this in the console:

Experimental support for decorators is a feature that is subject to change in a future release. Set the 'experimentalDecorators' option in your 'tsconfig.json' or '--experimentalDecorators' to remove this warning.

If so, you are not alone. This question on Stack Overflow has gathered thousands of views and dozens of answers. But most of them simply suggest "enable the flag and forget it." Today, we will go further: we will understand what the experimental decorators warning in TypeScript is, where it comes from, how it works under the hood, and why TypeScript considers decorators "experimental" in the first place.

What Are Decorators in TypeScript (and Why Are They Experimental)?

Decorators are a powerful metaprogramming tool. They allow you to annotate and modify classes, methods, properties, and parameters at runtime. If you have worked with Angular, NestJS, or TypeORM, you have already encountered them:

@Component({\n  selector: 'app-root',\n  templateUrl: './app.component.html'\n})\nclass AppComponent {}

But here is the catch: the JavaScript standard for decorators (TC39 proposal) is still at Stage 3. This means the syntax and semantics may change. TypeScript, being a superset of JavaScript, cannot simply "freeze" the implementation — it offers experimental support for decorators via the experimentalDecorators flag.

When you enable this option, the TypeScript compiler generates code that may become outdated or break when the standard is updated. That is why it honestly warns you: "Use at your own risk."

How Does the Experimental Decorators Warning Work Under the Hood of the Compiler?

To understand the warning, let's look inside the TypeScript source code. In the file checker.ts (yes, that is a real file inside the compiler), there is a function checkGrammarForDecorator. When the parser encounters a decorator, the compiler checks whether the experimentalDecorators flag is set in tsconfig.json.

If the flag is not set, it generates a diagnostic message — that very warning. It is not an error (the code will still compile), but the compiler persistently reminds you: "Hey, you are using a feature that may change!"

Here is what the simplified logic looks like:

// Pseudocode of the actual TypeScript logic\nfunction checkDecoratorUsage(decorator: Decorator, options: CompilerOptions) {\n  if (!options.experimentalDecorators) {\n    reportDiagnostic({\n      code: 1219,\n      message: "Experimental support for decorators is a feature that is subject to change in a future release..."\n    });\n  }\n}

Error code 1219 is exactly the warning you see. And code 1220 is a similar warning for emitDecoratorMetadata (another experimental flag, which we will discuss below).

How to Disable the Experimental Decorators Warning: 3 Ways

The simplest way is to add the flag to tsconfig.json:

{\n  "compilerOptions": {\n    "experimentalDecorators": true\n  }\n}

If you are using the command line:

tsc --experimentalDecorators

Or if you don't have a tsconfig.json, you can pass the flag directly:

npx tsc --experimentalDecorators src/index.ts

After this, the warning will disappear. But this is just the tip of the iceberg. Let's break down what actually happens when you enable experimentalDecorators.

What Does the Compiler Generate Under the Hood?

When you write a class decorator