{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strict": true,
    "esModuleInterop": true
  }
}

3. Add path aliases if you want to import from workspace packages directly:

{
  "compilerOptions": {
    "paths": {
      "@tsed/core": ["./packages/core/src/index.ts"],
      "@tsed/config": ["./packages/config/src/index.ts"]
    }
  }
}

4. Import reflect-metadata at the top of your application entry point before any decorator-using code:

import "reflect-metadata";

5. Environment variables: If using EnvsConfigSource or DotEnvsConfigSource, ensure your .env file is present at project root or configure the path explicitly via the provider options.

6. Register config providers by importing the desired provider entry point (this triggers the afterResolveConfiguration hook side-effect automatically):

import "@tsed/config/src/providers/dotenv";
import "@tsed/config/src/providers/envs";

Public API

ConfigSource (interface)

// config/src/interfaces/ConfigSource.ts
export interface ConfigSource {
  load(): Promise<Record<string, unknown>> | Record<string, unknown>;
}

export interface ConfigurationExtends {
  [key: string]: unknown;
}

Implement this interface to create a custom configuration source. The load() method must return a plain object; it is called during the afterResolveConfiguration lifecycle hook and its result is merged into the application configuration.

getConfigSources

// config/src/utils/getConfigSources.ts
export function getConfigSources(configuration: TsED.Configuration): ConfigSource[];

Retrieves all registered ConfigSource instances from the current application configuration. Use this inside a hook or custom provider to enumerate and invoke every config source in the correct order before the DI container finalizes settings.

withOptions

// config/src/utils/withOptions.ts
export function withOptions<T>(source: new (...args: any[]) => T, options: Record<string, unknown>): T;

A factory helper that instantiates a ConfigSource class and merges additional runtime options into it. Use it when registering a config provider programmatically to pass environment-specific parameters (file paths, prefixes, flags) without subclassing.

afterResolveConfiguration (hook)

// config/src/hooks/afterResolveConfiguration.ts
// Registers a Ts.ED lifecycle hook that iterates all ConfigSource instances
// and merges their outputs into the resolved configuration object.

This module registers itself as a side-effect when imported. It hooks into Ts.ED's configuration resolution lifecycle and ensures every registered ConfigSource is loaded and merged before the application bootstraps. You do not call it directly; importing it is sufficient.

Working examples

Scenario - Custom configuration source

Implement a custom ConfigSource that reads from a remote endpoint and integrate it into a Ts.ED server configuration.

import "reflect-metadata";
import { ConfigSource } from "./packages/config/src/interfaces/ConfigSource.js";
import { withOptions } from "./packages/config/src/utils/withOptions.js";
import "./packages/config/src/hooks/afterResolveConfiguration.js";

class RemoteConfigSource implements ConfigSource {
  private url: string;

  constructor(options: { url: string }) {
    this.url = options.url;
  }

  async load(): Promise<Record<string, unknown>> {
    const res = await fetch(this.url);
    return res.json();
  }
}

// Instantiate with runtime options
const remoteSource = withOptions(RemoteConfigSource, {
  url: "https://config.internal/api/settings"
});

// remoteSource.load() will fetch and return config values
remoteSource.load().then(config => {
  console.log("Remote config loaded:", config);
});

Scenario - Dotenv provider wiring

Wire the dotenv config provider into a Ts.ED application by importing its entry point, which registers the afterResolveConfiguration hook automatically.

import "reflect-metadata";
// Importing this module registers the dotenv config source hook
import "./packages/config/src/providers/dotenv/index.js";

// Now any TsED server configured with `extends` will have
// dotenv values available during bootstrap.
// Example server bootstrap (assuming @tsed/common is installed):
import { Configuration } from "@tsed/di";

@Configuration({
  // The 'extends' key is typed via the global TsED.Configuration augmentation
  extends: {
    dotenv: { path: "./.env.production" }
  }
})
class Server {}

Scenario - Inspecting registered config sources at runtime

Use getConfigSources inside a custom provider or hook to enumerate all active configuration sources and log them for diagnostics.

import "reflect-metadata";
import { getConfigSources } from "./packages/config/src/utils/getConfigSources.js";
import "./packages/config/src/providers/envs/index.js";
import "./packages/config/src/providers/json/index.js";

async function diagnoseConfig(configuration: TsED.Configuration) {
  const sources = getConfigSources(configuration);

  console.log(`Found ${sources.length} config source(s):`);

  for (const source of sources) {
    const data = await Promise.resolve(source.load());
    console.log("Source output keys:", Object.keys(data));
  }
}

// Call during your application's bootstrap diagnostic phase
diagnoseConfig({ extends: {} } as TsED.Configuration);

File walkthrough

• config/src/index.ts - Public barrel for the config package; re-exports constants, hooks, interfaces, and utilities.
• config/src/constants/constants.ts - Named constants used across the config subsystem (token names, default values).
• config/src/interfaces/ConfigSource.ts - Defines the ConfigSource interface and ConfigurationExtends type.
• config/src/interfaces/index.ts - Augments the global TsED.Configuration namespace to include the extends property.
• config/src/hooks/afterResolveConfiguration.ts - Side-effect module that registers the configuration resolution lifecycle hook.
• config/src/utils/getConfigSources.ts - Utility to extract all ConfigSource instances from a configuration object.
• config/src/utils/withOptions.ts - Factory helper for instantiating config sources with injected options.
• config/src/utils/jsonParse.ts - Safe JSON parsing utility used internally by JSON and dotenv providers.
• config/src/utils/validate.ts - AJV-backed validation utility for config source output schemas.
• config/src/providers/dotenv/ - DotEnvsConfigSource: loads .env files via dotenv.
• config/src/providers/envs/ - EnvsConfigSource: maps process.env variables into the configuration.
• config/src/providers/json/ - JsonConfigSource: reads and merges a JSON file into configuration.
• config/src/providers/yaml/ - YamlConfigSource: reads and merges a YAML file into configuration.
• core/src/decorators/ - storeFn, storeMerge, storeSet: low-level decorator builder utilities.
• core/src/errors/ - UnsupportedDecoratorType: error thrown when a decorator is applied to an invalid target.
• core/src/types/ - Shared TypeScript utility types: AnyDecorator, Store, Type, Env, Metadata, etc.
• core/src/utils/ - General-purpose utilities: ancestorOf, classOf, cleanObject, createInstance, decorateMethodsOf, and HTTP helpers.

Common pitfalls and fixes

• Missing reflect-metadata import: Decorators silently fail if reflect-metadata is not imported before any decorated class. Fix: add import "reflect-metadata" as the very first line of your entry point.
• ESM .js extension in imports: The source uses .js extensions in all internal imports (ESM convention). If your bundler or ts-node setup does not handle this, set "moduleResolution": "Bundler" or "Node16" in tsconfig.json.
• experimentalDecorators not enabled: TypeScript will emit errors on all decorator usage. Fix: set both "experimentalDecorators": true and "emitDecoratorMetadata": true in tsconfig.json.
• Config hook not triggered: If afterResolveConfiguration never fires, you likely forgot to import the provider entry point (e.g., config/src/providers/dotenv/index.js). These imports are required side-effects.
• AJV version mismatch: config/src/utils/validate.ts targets AJV v8. Installing AJV v6 will cause runtime errors. Fix: npm install ajv@^8.
• globby ESM-only: globby v13+ is ESM-only and cannot be require()d. Ensure your project runs in ESM mode or pin to globby@^11 for CJS compatibility.

Vibe-coding prompt template

I have purchased the Ts.ED framework source block. The source files are in the `source/` directory of this project. I also have a `USAGE.md` file explaining the API.

The upstream package is `@tsed/root@8.26.2`.

Please help me integrate this source into my existing Node.js/TypeScript Express backend step by step:

1. Read `USAGE.md` and `source/config/src/index.ts` to understand the public API.
2. Add the required dependencies listed in `USAGE.md` to my `package.json`.
3. Update my `tsconfig.json` to enable `experimentalDecorators`, `emitDecoratorMetadata`, and the correct `moduleResolution`.
4. Wire `source/config/src/providers/dotenv` and `source/config/src/providers/envs` into my application entry point.
5. Create a custom `ConfigSource` implementation that loads settings from my database, using the `ConfigSource` interface from `source/config/src/interfaces/ConfigSource.ts`.
6. Register it using `withOptions` from `source/config/src/utils/withOptions.ts`.
7. Show me a diagnostic function using `getConfigSources` from `source/config/src/utils/getConfigSources.ts` that logs all config sources at startup.
8. Ensure `import "reflect-metadata"` is placed correctly.

Do not invent any APIs. Only use exports visible in USAGE.md and the source files.

License and credit

Ts.ED is released under the MIT License. See source/LICENSE if present, or refer to the official repository. Upstream package: @tsed/root on npm. Credit: Romain Lenzotti and the Ts.ED contributors.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

NestJS Progressive Node.js Backend Framework

Automation, Utilities & Developer Tools

Free