define-config-ts

English | 简体中文

极简 *.config.ts 加载器 — 在现代 Node.js 上零额外依赖。

快速开始

pnpm add define-config-ts

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

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

为什么不用 c12 / unconfig？

c12 和 unconfig 功能很强，支持多种格式（ts、mts、cts、js、mjs、cjs、json 等）以及复杂的配置合并。

但有时候你只需要加载 *.config.ts。在 valaxy 中做过的简单 benchmark：

| 工具 | 加载时间 | | --- | --- | | unconfig | ~2-3 s | | c12 | ~0.2 s | | define-config-ts | ~0.6 ms |

如果你需要更广泛的格式支持或配置合并，请使用 c12 或 unconfig。 如果你只想要一个极简、快速的 *.config.ts 加载器 — 就是它了。

特性

• Fresh reload 友好：当 moduleCache 为 false（默认值）且存在 jiti 时，重复加载可以在 dev/HMR 流程中拿到变更后的配置。
• 原生兼容：在现代 Node.js 的原生 TypeScript 加载可用时，无需额外依赖即可工作；若未安装 jiti，会回退到原生 import()。注意：没有 jiti 时 Node 内置模块缓存生效，moduleCache: false 无法强制重新加载。
• 类型安全：通过 defineDefineConfig<T>() 创建带类型提示的 defineConfig 辅助函数。

兼容性

| Node.js | 加载策略 | 额外依赖 | | --- | --- | --- | | >= 22.6（原生 TS 支持） | 优先使用 jiti 以支持 fresh reload；未安装时回退到原生 import() | 无（推荐：pnpm add jiti） | | 18.x / 20.x | jiti | pnpm add jiti |

提示：在现代 Node.js 上安装 jiti 可启用 moduleCache: false（默认值），使重复加载始终拿到最新配置——这在 HMR / dev-server 场景中至关重要。

旧版 Node.js 请同时安装 jiti：

pnpm add define-config-ts jiti

使用

加载配置

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

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

用户侧配置文件

import { defineConfig } from 'your-lib'

export default defineConfig({
  // your config
})

创建带类型的 defineConfig

import { defineDefineConfig } from 'define-config-ts'

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

export const defineConfig = defineDefineConfig<LibConfig>()

Sponsors

License

MIT License © YunYouJun