⚙️ Configer

Production-grade config loader with cosmiconfig-level capabilities and a clean original API

💡 Highlights

🎯 Deterministic config resolution with 4 search strategies (none, project, workspace, global) and 40+ default search places per module name
📦 First-class support for 10+ formats — JSON, YAML, TOML, JSON5, JSONC, .env, JS/TS modules, and package.json properties — with both async and sync loaders
🔗 Config inheritance ($import/extends), environment overlays ($env/$development), schema validation, and plugin hooks — all built-in with zero config
🏗️ Clean Architecture internals with full DI container, making every component testable, replaceable, and independently extensible

📖 Description

Configer is a typed, extensible configuration loader for Node.js that resolves config files across project, workspace, and global scopes — with deterministic search plans, config inheritance chains, environment overlays, schema validation, and plugin lifecycle hooks.

Built with clean architecture principles (domain → application → infrastructure → presentation layers) and powered by a dependency injection container, Configer delivers the flexibility of cosmiconfig with stronger type safety, explicit error codes, and a modular internal design.

Real-World Use Cases

CLI Tools & Dev Tooling: Automatically discover .toolrc, .toolrc.yaml, tool.config.ts, or package.json properties — just like ESLint, Prettier, and Babel do — but with full TypeScript generics and schema validation out of the box.
Monorepo Configuration: Use the workspace search strategy to traverse from any nested package up to the workspace root, merging shared base configs with per-package overrides.
Multi-Environment Apps: Define $development, $production, or $env blocks directly in config files. Configer strips inactive environments and deep-merges the active one — no extra tooling required.
Plugin Ecosystems: Extend the config lifecycle with beforeFind, afterRead, and onError hooks to inject defaults, validate against external schemas, or log diagnostics.
Library Authors: Ship a typed config contract (IConfigOptions<TEntity>) so consumers get autocomplete and compile-time safety for your tool's configuration.

🛠️ Tech Stack

Category	Technologies
Language	TypeScript
Runtime	Node.js >= 20.0.0
Build Tool	Rollup, TypeScript Compiler
Testing	Vitest, V8 Coverage
Linting	ESLint, Prettier
Package Manager	npm
CI/CD	Semantic Release, Husky, Commitlint
Dependencies	yaml, smol-toml, json5, jsonc-parser, dotenv, @elsikora/cladi

🚀 Features

✨ **Async & Sync Clients — createConfiger() for async IO with watch support; createConfigerSync() for synchronous-only flows with strict fail-fast guarantees**
✨ **10+ Built-in Loaders — JSON, JSON5, JSONC, YAML, TOML, .env, JS (.js/.cjs/.mjs), TypeScript (.ts/.cts/.mts), and package.json property extraction**
✨ **4 Search Strategies — none (current directory), project (up to package.json), workspace (up to monorepo root), global (including XDG config home)**
✨ **Config Inheritance — Merge parent configs via extends or $import directives with circular reference detection and source chain tracking**
✨ **Environment Overlays — $development, $production, or $env map blocks are deep-merged for the active environment and stripped from output**
✨ **Built-in Schema Validation — Declare required fields, types, defaults, nested objects, array items, and custom validators without external dependencies**
✨ **Plugin Lifecycle Hooks — beforeFind, afterFind, beforeRead, afterRead, and onError hooks for extending every stage of config resolution**
✨ **Custom Loaders — Register async/sync loaders for any file extension (.ini, .xml, .custom) via the loaders option**
✨ **Watch Mode — File system watcher with debounced refresh, automatic cache invalidation, and clean IWatchHandle.close() cleanup**
✨ **Caching Layer — Separate find/read caches with granular clearFindCache(), clearReadCache(), and clearCaches() controls**
✨ **Stable Error Codes — Every failure throws ConfigError with a machine-readable CODE and human-readable SUGGESTIONS array**
✨ **Clean Architecture — Domain-driven layers (domain → application → infrastructure → presentation) with full DI container for testability**

🏗 Architecture

System Architecture

flowchart TD
    presentation[Presentation Layer]
    application[Application Layer]
    domain[Domain Layer]
    infrastructure[Infrastructure Layer]
    presentation --> application
    presentation --> infrastructure
    application --> domain
    infrastructure --> application
    infrastructure --> domain
    subgraph presentation
        createConfiger[createConfiger]
        createConfigerSync[createConfigerSync]
    end
    subgraph infrastructure
        diContainer[DI Container]
        loaderRegistry[Loader Registry]
        searchResolvers[Search Resolvers]
        cacheAdapter[Memory Cache]
        schemaValidator[Schema Validator]
        deepMerge[Deep Merge]
        fileWatcher[File Watcher]
    end
    subgraph application
        resolveSearchPlan[ResolveSearchPlanUseCase]
    end
    subgraph domain
        configClient[IConfigClient]
        configResult[IConfigResult]
        configError[ConfigError]
        pluginContract[IConfigPlugin]
    end

Data Flow

sequenceDiagram
    participant User
    participant Client as ConfigClient
    participant Plugins as Plugin Hooks
    participant SearchPlan as ResolveSearchPlan
    participant Cache as MemoryCache
    participant Loader as LoaderRegistry
    participant Merge as DeepMerge
    participant Schema as SchemaValidator
    User->>Client: findConfig(searchFrom?)
    Client->>Plugins: beforeFind(context)
    Client->>Cache: getFindResult(key)
    alt Cache Hit
        Cache-->>Client: cached result
    else Cache Miss
        Client->>SearchPlan: execute(options)
        SearchPlan-->>Client: candidateFilepaths[]
        loop Each candidate
            Client->>Loader: load(filepath, content)
            Loader-->>Client: raw config
            Client->>Merge: resolveInheritance(extends/$import)
            Merge-->>Client: merged config
            Client->>Client: resolveEnvironmentOverrides($env)
            Client->>Schema: validate(config, descriptor)
            Schema-->>Client: validated config
        end
        Client->>Cache: setFindResult(key, result)
    end
    Client->>Plugins: afterFind(result, context)
    Client-->>User: IConfigResult or null

📁 Project Structure

Click to expand

Configer/
├── docs/
│   ├── api-reference/
│   │   ├── error-codes/
│   │   ├── factories/
│   │   ├── interfaces/
│   │   ├── types/
│   │   ├── _meta.js
│   │   └── page.mdx
│   ├── core-concepts/
│   │   ├── caching-and-watch/
│   │   ├── environment-overrides/
│   │   ├── inheritance-and-merge/
│   │   ├── resolution-flow/
│   │   ├── schema-validation/
│   │   ├── _meta.js
│   │   └── page.mdx
│   ├── getting-started/
│   │   ├── first-client/
│   │   ├── first-config-read/
│   │   ├── installation/
│   │   ├── sync-mode/
│   │   ├── _meta.js
│   │   └── page.mdx
│   ├── guides/
│   │   ├── custom-loaders/
│   │   ├── custom-search-places/
│   │   ├── package-json-property/
│   │   ├── plugins/
│   │   ├── watch-mode/
│   │   ├── _meta.js
│   │   └── page.mdx
│   ├── _meta.js
│   └── page.mdx
├── examples/
│   ├── 01-basic-usage/
│   │   └── main.ts
│   ├── 02-search-strategies/
│   │   └── main.ts
│   ├── 03-file-formats/
│   │   └── main.ts
│   ├── 04-inheritance/
│   │   └── main.ts
│   ├── 05-environment-overrides/
│   │   └── main.ts
│   ├── 06-plugins/
│   │   └── main.ts
│   ├── 07-schema-validation/
│   │   └── main.ts
│   ├── 08-custom-loaders/
│   │   └── main.ts
│   ├── 09-watch-mode/
│   │   └── main.ts
│   ├── 10-package-json-property/
│   │   └── main.ts
│   ├── README.md
│   └── tsconfig.json
├── scripts/
│   ├── clean.function.js
│   └── validate-documentation.function.js
├── src/
│   ├── application/
│   │   ├── dto/
│   │   ├── interface/
│   │   ├── use-case/
│   │   └── index.ts
│   ├── domain/
│   │   ├── entity/
│   │   ├── error/
│   │   ├── type/
│   │   └── index.ts
│   ├── infrastructure/
│   │   ├── adapter/
│   │   ├── cache/
│   │   ├── di/
│   │   ├── loader/
│   │   ├── resolver/
│   │   ├── service/
│   │   ├── watcher/
│   │   └── index.ts
│   ├── presentation/
│   │   ├── function/
│   │   └── index.ts
│   └── index.ts
├── test/
│   ├── e2e/
│   │   ├── configer-error-paths.end-to-end.test.ts
│   │   └── configer-integration.end-to-end.test.ts
│   └── unit/
│       ├── application/
│       ├── domain/
│       ├── infrastructure/
│       └── presentation/
├── commitlint.config.js
├── eslint.config.js
├── generated-logo.png
├── lint-staged.config.js
├── package-lock.json
├── package.json
├── prettier.config.js
├── README.md
├── release.config.js
├── rollup.config.js
├── tsconfig.build.json
├── tsconfig.json
├── vitest.config.js
├── vitest.end-to-end.config.js
└── vitest.unit.config.js

📋 Prerequisites

Node.js >= 20.0.0
npm >= 9.0.0 (or pnpm / yarn equivalent)
ESM-compatible project ("type": "module" in package.json)

🛠 Installation

# Using npm
npm install @elsikora/configer

# Using pnpm
pnpm add @elsikora/configer

# Using yarn
yarn add @elsikora/configer


Verify the installation:

ts
import { createConfiger } from '@elsikora/configer';

const client = createConfiger({ moduleName: 'my-app' });
console.log(typeof client.findConfig === 'function'); // true

💡 Usage

Basic Async Usage

import { createConfiger } from '@elsikora/configer';
import type { IConfigClient, IConfigResult } from '@elsikora/configer';

type AppConfig = {
  serviceName: string;
  isFeatureEnabled: boolean;
};

const client: IConfigClient<AppConfig> = createConfiger<AppConfig>({
  moduleName: 'my-app',
  cwd: process.cwd(),
});

const result: IConfigResult<AppConfig> | null = await client.findConfig();

if (result) {
  console.log(result.filepath); // /project/.my-apprc.json
  console.log(result.config?.serviceName); // "billing-api"
}

Sync Mode

import { createConfigerSync } from '@elsikora/configer';

const client = createConfigerSync<{ retries: number }>({
  moduleName: 'my-app',
});

const result = client.findConfig();
console.log(result?.config?.retries); // 3

Search Strategies

// Search only the current directory
const client = createConfiger({ moduleName: 'app', searchStrategy: 'none' });

// Ascend until nearest package.json
const client = createConfiger({ moduleName: 'app', searchStrategy: 'project' });

// Ascend until workspace root (.git, pnpm-workspace.yaml, etc.)
const client = createConfiger({ moduleName: 'app', searchStrategy: 'workspace' });

// Traverse project + workspace + global config directory
const client = createConfiger({ moduleName: 'app', searchStrategy: 'global' });

Config Inheritance

Create a base config (base.config.json):

{ "logLevel": "info", "retries": 1 }

Extend it in your app config (.my-apprc.json):

{
  "extends": "./base.config.json",
  "retries": 3
}

Result: { logLevel: "info", retries: 3 } with sources tracking the full chain.

Environment Overrides

{
  "apiUrl": "https://api.default.com",
  "$development": { "apiUrl": "https://dev.api.com" },
  "$env": {
    "production": { "apiUrl": "https://prod.api.com" }
  }
}

const client = createConfiger({
  moduleName: 'app',
  envName: 'development', // or reads NODE_ENV automatically
});

Schema Validation

import type { ISchemaDescriptor } from '@elsikora/configer';

const schema: ISchemaDescriptor<{ serviceName: string; retryCount: number }> = {
  type: 'object',
  properties: {
    serviceName: { type: 'string', isRequired: true },
    retryCount: { type: 'number', defaultValue: 3 },
  },
  shouldAllowUnknownProperties: false,
};

const client = createConfiger({
  moduleName: 'app',
  schema,
});

Plugin Hooks

const client = createConfiger({
  moduleName: 'app',
  plugins: [
    {
      name: 'source-marker',
      afterRead: (result) => ({
        ...result,
        config: { ...result.config, _loadedFrom: result.filepath },
      }),
      onError: (error) => console.error('Config error:', error.message),
    },
  ],
});

Custom Loaders

const client = createConfiger({
  moduleName: 'app',
  searchPlaces: ['config.ini'],
  shouldMergeSearchPlaces: false,
  loaders: {
    '.ini': {
      asyncLoader: (_filepath, content) => parseIni(content),
      syncLoader: (_filepath, content) => parseIni(content),
    },
  },
});

Watch Mode

const handle = client.watchConfig((error, result) => {
  if (error) return console.error(error);
  console.log('Config changed:', result?.config);
});

// Cleanup on shutdown
process.on('SIGTERM', () => handle.close());

Reading from package.json

const client = createConfiger({
  moduleName: 'my-tool',
  packageProperty: 'config.myTool', // or ['config', 'myTool']
  searchPlaces: ['package.json'],
  shouldMergeSearchPlaces: false,
});

🛣 Roadmap

Click to expand

Task / Feature	Status
Core async/sync config client with search strategies	✅ Done
Built-in loaders for JSON, YAML, TOML, JSON5, JSONC, .env, JS/TS	✅ Done
Config inheritance via `extends` and `$import` with cycle detection	✅ Done
Environment overrides (`$env`, `$development`, `$production`)	✅ Done
Built-in schema validation with nested objects and arrays	✅ Done
Plugin lifecycle hooks (beforeFind, afterRead, onError)	✅ Done
Watch mode with debounced file system monitoring	✅ Done
Clean Architecture with full DI container	✅ Done
Comprehensive unit and e2e test suites	✅ Done
MDX documentation site with guides and API reference	✅ Done
Remote config source support (HTTP/S3)	🚧 In Progress
Config encryption/decryption plugin	🚧 In Progress
JSON Schema / Zod adapter for schema validation	🚧 In Progress
Config diff and migration tooling	🚧 In Progress

❓ FAQ

Click to expand

How is Configer different from cosmiconfig?

Configer is inspired by cosmiconfig but built from scratch with TypeScript generics, Clean Architecture internals, and additional features: config inheritance, environment overlays, schema validation, plugin hooks, and watch mode — all built-in without extra packages.

Can I migrate from cosmiconfig?

Replace cosmiconfig(moduleName, options) → createConfiger({ moduleName, ...options })
Replace search() → findConfig()
Replace load(filepath) → readConfig(filepath)
Use createConfigerSync for synchronous API
Move custom transforms into plugins (beforeRead, afterRead, onError)

What file formats are supported out of the box?

JSON, JSON5, JSONC, YAML (.yaml/.yml), TOML, .env, JavaScript modules (.js/.cjs/.mjs), TypeScript modules (.ts/.cts/.mts), and package.json with nested property extraction.

Can I use this in a CommonJS project?

Configer is published as ESM only. Your project needs "type": "module" in package.json or you can use dynamic import() from CJS code.

When should I use the sync client vs async client?

Use createConfigerSync() only when your runtime strictly requires synchronous behavior (e.g., synchronous CLI startup). The sync client cannot load .mjs, .mts, or .ts files, and plugin hooks must not return Promises. For all other cases, prefer createConfiger() (async).

How does the search strategy work?

none: Only searches the start directory
project: Ascends directories until it finds a package.json
workspace: Ascends until a workspace root marker (.git, pnpm-workspace.yaml, turbo.json, etc.)
global: Combines project/workspace traversal with $XDG_CONFIG_HOME/<moduleName> or ~/.config/<moduleName>

How do I handle errors?

All errors are instances of ConfigError with a stable .CODE property for programmatic handling and a .SUGGESTIONS array with actionable fix recommendations. Use error.CODE for branching logic and error.message for user-facing output.

🔒 License

This project is licensed under MIT.

🙏 Acknowledgments

Inspired by cosmiconfig — the gold standard for config file discovery in the Node.js ecosystem
Built with @elsikora/cladi — a lightweight dependency injection container
Parsing powered by yaml, smol-toml, json5, jsonc-parser, and dotenv
Testing with Vitest and @elsikora/cladi-testing
Thanks to the open-source community for feedback and inspiration

Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.elsikora		.elsikora
.github		.github
.husky		.husky
docs		docs
examples		examples
scripts		scripts
src		src
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
commitlint.config.js		commitlint.config.js
eslint.config.js		eslint.config.js
lint-staged.config.js		lint-staged.config.js
package.json		package.json
prettier.config.js		prettier.config.js
release.config.js		release.config.js
rollup.config.js		rollup.config.js
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.js		vitest.config.js
vitest.end-to-end.config.js		vitest.end-to-end.config.js
vitest.unit.config.js		vitest.unit.config.js

ElsiKora/Configer

Folders and files

Latest commit

History

Repository files navigation

⚙️ Configer

💡 Highlights

📚 Table of Contents

📖 Description

Real-World Use Cases

🛠️ Tech Stack

🚀 Features

🏗 Architecture

System Architecture

Data Flow

📁 Project Structure

📋 Prerequisites

🛠 Installation

💡 Usage

Basic Async Usage

Sync Mode

Search Strategies

Config Inheritance

Environment Overrides

Schema Validation

Plugin Hooks

Custom Loaders

Watch Mode

Reading from package.json

🛣 Roadmap

❓ FAQ

How is Configer different from cosmiconfig?

Can I migrate from cosmiconfig?

What file formats are supported out of the box?

Can I use this in a CommonJS project?

When should I use the sync client vs async client?

How does the search strategy work?

How do I handle errors?

🔒 License

🙏 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages