Fixing the Error: Uncaught Reflect-metadata Shim Requirement while Using Class Decorators - Step by Step Guide

In this guide, we'll be addressing the error that occurs when using class decorators without properly including the necessary reflect-metadata shim. If you're encountering this error, it's likely that you're using TypeScript with decorators and have not included the reflect-metadata in your project. The error message you're encountering may look something like this:

Uncaught Error: reflect-metadata shim is required when using class decorators

Don't worry! This step-by-step guide will walk you through the process of fixing this error and ensure that your decorators function correctly.

Table of Contents

  1. Prerequisites
  2. Installing reflect-metadata
  3. Importing reflect-metadata
  4. Configuring TypeScript for decorators
  5. FAQ


Before we begin, make sure you have the following prerequisites in place:

  • Familiarity with TypeScript and decorators
  • A TypeScript project with decorators, where you're encountering the error

Installing reflect-metadata

The first step in resolving this error is to install the reflect-metadata package via npm. This package provides the necessary polyfill for metadata reflection, which is required when using class decorators. To install reflect-metadata, run the following command in your project's root directory:

npm install reflect-metadata --save

Importing reflect-metadata

Once you've installed the reflect-metadata package, you'll need to import it in your project. To do this, add the following import statement at the very top of your main TypeScript file (usually index.ts or main.ts):

import 'reflect-metadata';

By adding this import, you're ensuring that the reflect-metadata shim is included in your project, and the error should no longer occur.

Configuring TypeScript for decorators

In addition to importing reflect-metadata, you'll also need to make sure that your TypeScript configuration is set up correctly for decorators. To do this, open your tsconfig.json file and ensure that the following options are set:

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

The experimentalDecorators option enables decorator support in TypeScript, while the emitDecoratorMetadata option ensures that metadata is emitted for the decorators.

After making these changes, you should no longer encounter the "Uncaught Error: reflect-metadata shim is required when using class decorators" error. Your decorators should now function correctly.


1. What is the purpose of the reflect-metadata package?

The reflect-metadata package provides a polyfill for metadata reflection, which is required when using class decorators in TypeScript projects. This package ensures that the necessary metadata is available at runtime, allowing decorators to function correctly.

2. Do I need reflect-metadata for every TypeScript project with decorators?

If your TypeScript project is using decorators and requires metadata reflection, then you will need to include the reflect-metadata package. However, not all decorators require metadata reflection, so you may not need this package for every project that uses decorators.

3. Can I use other metadata reflection libraries instead of reflect-metadata?

Yes, you can use other libraries that provide metadata reflection, such as core-js. However, you'll need to ensure that the library you choose provides the necessary metadata reflection capabilities required by your decorators.

4. Is there any performance impact when using reflect-metadata?

Using the reflect-metadata package may have a slight impact on the performance of your application, as it introduces additional code and processing for metadata reflection. However, this impact is generally minimal and should not be a significant concern in most use cases.

5. Are decorators and metadata reflection supported in JavaScript projects?

Decorators and metadata reflection are currently not part of the JavaScript standard. However, you can use Babel with the babel-plugin-transform-decorators and babel-plugin-transform-metadata plugins to enable decorator and metadata reflection support in JavaScript projects.

Great! You’ve successfully signed up.

Welcome back! You've successfully signed in.

You've successfully subscribed to

Success! Check your email for magic link to sign-in.

Success! Your billing info has been updated.

Your billing was not updated.