# define-config-ts

[English](./README.md) | [简体中文](./README.zh-CN.md)

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![bundle][bundle-src]][bundle-href]
[![JSDocs][jsdocs-src]][jsdocs-href]
[![License][license-src]][license-href]

Minimalist `*.config.ts` loader — zero dependency on modern Node.js.

## Quick Start

```bash
pnpm add define-config-ts
```

```ts
import { loadConfig } from 'define-config-ts'

const { config, configFile } = await loadConfig({
  cwd: process.cwd(),
  name: 'your-lib', // loads your-lib.config.ts
})
```

## Why not `c12` / `unconfig`?

[c12](https://github.com/unjs/c12) and [unconfig](https://github.com/antfu-collective/unconfig) are powerful tools that support many formats (`ts`, `mts`, `cts`, `js`, `mjs`, `cjs`, `json`, …) and complex config merging.

But sometimes you only need `*.config.ts` — nothing else. A quick benchmark in [valaxy](https://github.com/YunYouJun/valaxy):

| Tool | Load time |
| --- | --- |
| `unconfig` | ~2-3 s |
| `c12` | ~0.2 s |
| `define-config-ts` | **~0.6 ms** |

If you need broader format support or config merging, use `c12` or `unconfig`.
If you want a minimal, fast `*.config.ts` loader — this is it.

## Features

- Fresh-load friendly: when `moduleCache` is `false` (default) and [jiti](https://github.com/unjs/jiti) is available, repeated loads can pick up config changes in dev/HMR flows.
- Native-compatible: on modern Node.js with built-in TypeScript loading, it works without extra dependencies and falls back to native `import()` when `jiti` is unavailable. Note: without `jiti`, Node's built-in module cache applies and `moduleCache: false` cannot force a fresh reload.
- Type-safe `defineConfig` helper via `defineDefineConfig<T>()`.

## Compatibility

| Node.js | Loading strategy | Extra dependency |
| --- | --- | --- |
| `>= 22.6` (native TS support) | Prefer `jiti` for fresh reloads; falls back to native `import()` | None (recommended: `pnpm add jiti`) |
| `18.x` / `20.x` | `jiti` | `pnpm add jiti` |

> **Tip**: On modern Node.js, installing `jiti` enables `moduleCache: false` (default) so that repeated loads always pick up the latest config — essential for HMR / dev-server workflows.

For older Node.js, install `jiti` alongside:

```bash
pnpm add define-config-ts jiti
```

## Usage

### Load config

```ts
import { loadConfig } from 'define-config-ts'

const { config, configFile } = await loadConfig({
  cwd: process.cwd(),
  name: 'your-lib', // loads your-lib.config.ts
})
```

### User-facing config file

```ts [your-lib.config.ts]
import { defineConfig } from 'your-lib'

export default defineConfig({
  // your config
})
```

### Create a typed `defineConfig`

```ts [your-lib/config.ts]
import { defineDefineConfig } from 'define-config-ts'

export interface LibConfig {
  features: { [key: string]: any }
}

export const defineConfig = defineDefineConfig<LibConfig>()
```

## Sponsors

<p align="center">
  <a href="https://cdn.jsdelivr.net/gh/YunYouJun/sponsors/public/sponsors.svg">
    <img src='https://cdn.jsdelivr.net/gh/YunYouJun/sponsors/public/sponsors.svg' alt='Sponsors'/>
  </a>
</p>

## License

[MIT](./LICENSE) License © [YunYouJun](https://github.com/YunYouJun)

<!-- Badges -->

[npm-version-src]: https://img.shields.io/npm/v/define-config-ts?style=flat&colorA=080f12&colorB=1fa669
[npm-version-href]: https://npmjs.com/package/define-config-ts
[npm-downloads-src]: https://img.shields.io/npm/dm/define-config-ts?style=flat&colorA=080f12&colorB=1fa669
[npm-downloads-href]: https://npmjs.com/package/define-config-ts
[bundle-src]: https://img.shields.io/bundlephobia/minzip/define-config-ts?style=flat&colorA=080f12&colorB=1fa669&label=minzip
[bundle-href]: https://bundlephobia.com/result?p=define-config-ts
[license-src]: https://img.shields.io/github/license/YunYouJun/define-config-ts.svg?style=flat&colorA=080f12&colorB=1fa669
[license-href]: https://github.com/YunYouJun/define-config-ts/blob/main/LICENSE
[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
[jsdocs-href]: https://www.jsdocs.io/package/define-config-ts