Understanding the Experimental Decorators Warning in TypeScript

By the end of this page, you will understand what the experimentalDecorators warning means in TypeScript, why it can still appear even when the option is enabled, and how to troubleshoot configuration, tooling, and project-structure issues that cause inconsistent behavior.

Decorators in TypeScript are a language feature that must be explicitly enabled. The experimentalDecorators compiler option tells TypeScript that your project intentionally uses decorators.

If that option is enabled and you still see the warning, the most important idea is this:

• the file may not actually be compiled with the tsconfig.json you think it is
• a different tool may be compiling the file
• the editor may be using a different TypeScript project context
• some files may belong to another tsconfig.json or no project at all

In real projects, TypeScript code is often handled by more than one system:

• the TypeScript compiler (tsc)
• your editor's TypeScript language service
• a bundler such as Webpack, Vite, or esbuild
• a test runner
• Babel or another transpiler

That means one part of your setup may respect experimentalDecorators, while another part may ignore it or use a different config.

This matters because many TypeScript problems are not caused by syntax errors. They are caused by configuration scope: which files are included, which config is active, and which tool is reading it.

Think of tsconfig.json like a rulebook for a classroom.

You assume every student is following the same rulebook, but in reality:

• some students are in a different classroom
• some are using last week's rulebook
• some are being taught by a substitute teacher

Decorators warnings often happen for the same reason. You enabled the rule in one tsconfig.json, but some files are being checked under a different rulebook.

So the question is usually not "Did I set experimentalDecorators?" but "Which config is this file actually using?"

The relevant TypeScript configuration looks like this:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

A simple decorator example:

function sealed(constructor: Function) {
  Object.seal(constructor);
  Object.seal(constructor.prototype);
}

@sealed
class UserService {
  getUser() {
    return "Alice";
  }
}

What these options do

• experimentalDecorators: true
  • Allows decorator syntax like @sealed

Consider this project structure:

project/
  tsconfig.json
  src/
    app.ts
  scripts/
    generate.ts

And this tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true
  },
  "include": ["src/**/*"]
}

Now imagine these files:

// src/app.ts
function logClass(target: Function) {}

@logClass
class App {}

// scripts/generate.ts
function logClass(target: Function) {}

@logClass
  {}

Decorators are commonly used in frameworks and libraries that attach metadata or modify behavior.

Common examples

• Angular
  • @Component, @Injectable, @Directive
• NestJS
  • @Controller, @Get, @Injectable
• TypeORM
  • @Entity, @Column, @PrimaryGeneratedColumn
• Custom app infrastructure
  • logging decorators
  • validation decorators
  • permission decorators
  • caching decorators

Why the warning matters in practice

If one part of your app compiles with decorators enabled and another does not:

• builds may fail only in certain environments
• editors may show warnings that CI does not
• test files may behave differently from app files
• generated metadata may be missing in one part of the system

This is especially common in monorepos, apps with multiple tsconfig files, and projects using both Babel and TypeScript.

In real codebases, developers usually solve this by making configuration explicit and shared.

Common patterns

1. Base config inheritance

Create a shared base config:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Then extend it:

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

This avoids one config accidentally missing decorator support.

2. Separate app and test configs

1. Assuming emitDecoratorMetadata enables decorators

Broken assumption:

{
  "compilerOptions": {
    "emitDecoratorMetadata": true
  }
}

Why it fails:

• emitDecoratorMetadata only adds metadata
• it does not allow @decorator syntax

Fix:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

2. File is outside the include pattern

Broken config:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Quick rules

• experimentalDecorators enables decorator syntax
• emitDecoratorMetadata does not enable decorators by itself
• a file must belong to the correct TypeScript project to get those settings
• multiple tsconfig files can cause inconsistent behavior
• editor warnings may differ from terminal builds

Useful checks

tsc --showConfig

tsc -p tsconfig.json

Things to inspect

• Is the file inside include?
• Is the file excluded?
• Is there another tsconfig closer to that file?
• Does the project use extends?

Why do I get the decorators warning even though experimentalDecorators is true?

Usually because the file is not being compiled with the tsconfig.json you edited, or your editor is using a different TypeScript project context.

Why do only some files show the warning in the same project?

Those files may belong to a different tsconfig, be outside the include pattern, or be treated as inferred standalone files by the editor.

Does emitDecoratorMetadata enable decorators in TypeScript?

No. It only emits additional metadata. You still need experimentalDecorators: true.

How can I check which TypeScript config is being used?

Use tsc --showConfig for the active project config, and check your editor's TypeScript project information if available.

Can the problem come from my editor rather than the compiler?

Yes. Editors often run their own TypeScript language service, which can use a different TypeScript version or detect a different project.

Can multiple tsconfig.json files cause this issue?

Yes. This is one of the most common reasons for inconsistent decorator warnings.

Should I restart the TypeScript server after changing tsconfig.json?

Yes. Some editors cache project state, so restarting the TypeScript service can clear stale warnings.

• TypeScript tsconfig — Decorator support depends on compiler configuration.
• TypeScript include and exclude — Files outside the project often behave differently.
• TypeScript project references — Large projects may split code across multiple configs.
• Workspace vs bundled TypeScript — Editors may use a different TypeScript version than your project.
• Babel decorators — Babel has its own decorator handling and configuration.
• TypeScript metadata reflection — Relevant when using emitDecoratorMetadata.
• Angular decorators — A common real-world source of this warning.
• NestJS decorators — Another common framework that depends heavily on decorator support.