xTaskjs 1.0 is live: role-based accounts, documentation, and a customizable interface.

EN ES
Log in Register

Packages

@xtaskjs/config

Typed, fail-fast environment configuration with Zod-powered schema validation.

Back to catalog View source
npm install @xtaskjs/config zod Package path: packages/config

Overview

What this package owns in the runtime

Config centralizes environment loading and validation so applications fail fast when required variables are missing or invalid. It exposes a typed ConfigService through DI and supports env-file loading plus optional prefixed variable mapping.

What it provides

  • ConfigModule.register() and ConfigModule.registerAsync() provide synchronous and factory-driven bootstrap flows.
  • Schema validation runs before traffic is served, so invalid env state fails startup early.
  • InjectConfigService() and getConfigService() expose typed values inside DI-managed services.
  • Prefix mapping can resolve logical keys from prefixed variables such as DB_HOST and DB_PORT.

How it fits

  • Used across upstream samples to register NODE_ENV, PORT, and runtime tuning variables before CreateApplication().
  • Fits naturally with @xtaskjs/core lifecycle because config validation runs before route handling begins.
  • Pairs with @xtaskjs/security, @xtaskjs/typeorm, and other modules to centralize credentials and endpoint settings.

Usage Chart

How strongly this package shapes the runtime

Bootstrap

5/5

Dependency Injection

4/5

Configuration

5/5

Operations

4/5

Integrations

5/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

Register schema, env files, and optional prefix settings so required variables are known before other integrations initialize.

During CreateApplication()

Config validation runs early, then ConfigService and related lifecycle tokens are published into the container for DI-managed classes.

During app.close()

The config lifecycle releases in-memory runtime state while environment values remain immutable process inputs.

API Surface

Representative exports from the upstream package

Usage

Typical adoption flow

1. Register a schema

Use ConfigModule.register() with a Zod schema to define the canonical environment contract for your app.

2. Load env files safely

Set envFiles and optional prefix mapping so local and deployed environments resolve variables consistently.

3. Inject typed config

Use InjectConfigService() in services and startup modules instead of reading process.env directly in business code.

Example

Reference snippet

Schema-first configuration module
import { z } from "zod";
import { ConfigModule, InjectConfigService, type ConfigService } from "@xtaskjs/config";

const AppConfigSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  PORT: z.coerce.number().int().positive().default(3000),
  DATABASE_URL: z.string().url(),
});

ConfigModule.register({
  schema: AppConfigSchema,
  envFiles: [".env", ".env.local"],
});

class AppSettingsService {
  @InjectConfigService()
  private readonly config!: ConfigService<z.infer<typeof AppConfigSchema>>;

  getPort() {
    return this.config.get("PORT");
  }
}

Samples

Official samples to inspect next

Reference samples: 01-new_app, 03-fastify_app, 06-security_app, 09-internationalization_app, 18-value_objects_app, 26-bots_app, 27-bots_webhook_security_app