Reflect-Metadata for TypeScript: Complete Guide with Examples

Welcome to this in-depth guide on the reflect-metadata library for TypeScript. This library is the foundation for many modern frameworks, including Angular, NestJS, and TypeORM. It lets you add and read metadata (data about data) for classes, methods, properties, and parameters at runtime. If you want to understand how decorators and Dependency Injection (DI) work in TypeScript, mastering reflect-metadata is essential.

1. What Is It and Why Do You Need It?

reflect-metadata is a polyfill (implementation) for the built-in Reflect object, which is part of the ES2016 (ES7) specification. Its main purpose is to provide an API for working with metadata that can be associated with various code elements (classes, methods, properties). Standard JavaScript lacks this functionality, so TypeScript requires a separate package.

Why is this useful? Imagine you're building a framework. You need to know what dependencies a class requires, which routes are tied to controller methods, or which entity fields should be serialized to JSON. Without metadata, you'd have to store this info in separate config files or use complex patterns. reflect-metadata lets you store this information directly in your code, making it more self-documenting and easier to analyze.

The library is closely tied to decorators. A decorator is a function applied to a class, method, or property. Inside a decorator, you can call Reflect.defineMetadata to save information, and elsewhere in your program, use Reflect.getMetadata to retrieve it. This is the foundation for implementing Dependency Injection, ORM (Object-Relational Mapping), validation, and many other patterns.

2. Installation

Install the library via npm (Node Package Manager). Make sure you have Node.js (version 12 or higher) installed.

npm install reflect-metadata --save

After installation, import the library at the very top of your entry file (usually main.ts or index.ts) so it becomes globally available.

import "reflect-metadata";

Important: This import must come before any other code that uses Reflect. If you're using a framework (e.g., Angular), it handles this automatically. Otherwise, add this line at the top of your file.

You also need to enable decorator and metadata support in your tsconfig.json file:

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

The emitDecoratorMetadata flag tells the TypeScript compiler to generate type metadata for decorated elements. This is required for many frameworks to work correctly.

3. Quick Start — Minimal Working Example

Let's create a simple example that demonstrates how to add metadata to a class and read it back.

import "reflect-metadata";

// 1. Define a key for the metadata
const METADATA_KEY = "my_custom_key";

// 2. Create a decorator that adds metadata
function MyDecorator(value: string) {
    return function (target: any) {
        // target is the class constructor
        Reflect.defineMetadata(METADATA_KEY, value, target);
    };
}

// 3. Apply the decorator to a class
@MyDecorator("This is my class")
class MyClass {
    greet() {
        console.l