@glorhythm/config-loader

A lightweight and strongly-typed configuration loader for Node.js projects.
It automatically loads environment variables from .env, collects configuration files from the configs/ directory, and provides type-safe access to nested configuration values at runtime.

✨ Features

• 📦 Auto-load .env and configs/ files
• 🔍 Type-safe config access
• 🧩 Automatic ConfigData interface generation (via @glorhythm/type-gen)
• 📁 Works seamlessly with both JavaScript and TypeScript
• ⚙️ No boilerplate — just ConfigLoader.load() and go

📦 Installation

npm install @glorhythm/config-loader
# or
yarn add @glorhythm/config-loader

📁 Project Structure

Your project should have a configs directory and a .env file:

project/
├─ src/
│  ├─ configs/
|  │  ├─ app.ts
|  │  ├─ database.ts
|  │  └─ redis.ts
│  └─ index.ts
├─ .env
└─ package.json

• .env – stores environment variables (e.g., APP_PORT=3000)
• configs/ – each file exports an object with configuration for a specific module

🚀 Usage

1. Load environment and config files

import { ConfigLoader } from "@glorhythm/config-loader";

ConfigLoader.load(); // Loads .env + configs/*.ts

This will:

• Parse .env
• Load all config files from configs/
• Merge them into a single ConfigData object
• Automatically generate a ConfigData interface in development mode

2. Access configuration values (type-safe)

Use the Config helper to access deeply nested values with autocompletion and type safety:

import Config from "@glorhythm/config-loader";

const port = Config("app.port"); // ✅ inferred as number
const redisHost = Config("redis.host"); // ✅ inferred as string

console.log(`Server running on port ${port}`);

If the path doesn’t exist, Config() will return null.

3. Direct API via ConfigLoader.get()

If you prefer, you can directly call:

import { ConfigLoader } from "@glorhythm/config-loader";

const dbName = ConfigLoader.get("database.name");

🧠 Types & Utilities

The library ships with two powerful utility types for type-safe key access:

• DotPath<T> – Generates all possible dot-notation paths from a nested object
• PathValue<T, P> – Resolves the type of a nested path

Example:

type Path = DotPath<ConfigData>;
// "app.port" | "app.env" | "redis.host" | "redis.port" | ...

type Value = PathValue<ConfigData, "redis.host">;
// string

⚙️ Configuration File Example

// configs/app.ts
export default {
  name: "MyApp",
  env: "development",
  port: 3000,
};

// configs/redis.ts
export default {
  host: "127.0.0.1",
  port: 6379,
};

🛠️ API Reference

ConfigLoader.load()

Loads .env, parses all config files, and initializes the internal configuration map.

ConfigLoader.get(path: DotPath<ConfigData>): PathValue<ConfigData, P> | null

Fetch a nested config value with type inference.

Config<P>(path: P): PathValue<ConfigData, P> | null

Shortcut for ConfigLoader.get().

🧪 Auto Type Generation

When NODE_ENV ≠ production, the loader uses @glorhythm/type-gen to generate a ConfigData interface from your runtime configuration.
This ensures your TypeScript types always stay in sync with the actual config structure — no manual typing required.

📜 License

MIT © glorhythm

🤝 Contributing

Contributions, issues, and feature requests are welcome!
Feel free to open a PR or start a discussion in the repository.

📬 Author

glorhythm
Building powerful developer tooling — one library at a time 🚀