@holix/config

Type-safe configuration schema for Holix framework using Zod.

特性

• 🔒 类型安全 - 使用 Zod 定义的强类型配置
• ✅ 运行时验证 - 自动验证配置的正确性
• 📝 详细错误 - 提供清晰的验证错误信息
• 🔧 灵活配置 - 支持多种配置模式
• 🎯 智能推断 - TypeScript 类型自动推断

安装

pnpm add @holix/config

使用

基础用法

import { parseConfig, validateConfig } from '@holix/config'

// 验证配置（返回结果对象）
const result = validateConfig({
  appID: 'my-app',
  app: { entry: 'src/index.ts' },
  outDir: 'dist'
})

if (result.success) {
  console.log('Valid config:', result.data)
}
else {
  console.error('Validation errors:', result.error.issues)
}

// 解析配置（抛出异常）
try {
  const config = parseConfig({
    appID: 'my-app',
    app: { entry: 'src/index.ts' }
  })
  console.log('Parsed config:', config)
}
catch (error) {
  console.error('Invalid config:', error)
}

配置类型

import type { HolixConfig } from '@holix/config'

const config: HolixConfig = {
  appID: 'my-app',

  // 单入口模式
  app: {
    entry: 'src/index.ts'
  },

  // 或者多页面模式（与 app 互斥）
  // directories: {
  //   pages: 'src/pages'
  // },

  // 预加载脚本（多种格式）
  preload: 'src/preload.ts',
  // 或 preload: ['src/preload1.ts', 'src/preload2.ts']
  // 或 preload: { main: 'src/preload-main.ts', worker: 'src/preload-worker.ts' }

  outDir: 'dist',
  plugins: []
}

合并配置

import { defaultHolixConfig, mergeConfig } from '@holix/config'

// 用户配置会与默认配置合并
const config = mergeConfig({
  appID: 'my-app',
  app: { entry: 'src/main.ts' }
})

console.log(config)
// {
//   appID: 'my-app',
//   app: { entry: 'src/main.ts' },
//   outDir: 'dist',  // 来自默认配置
//   directories: { pages: 'src/pages' },  // 来自默认配置
//   preload: null,
//   plugins: []
// }

在配置文件中使用

// holix.config.ts
import { defineConfig } from '@holix/config'

export default defineConfig({
  appID: 'my-app',
  app: {
    entry: 'src/index.ts'
  },
  outDir: 'dist',
  preload: {
    main: 'src/preload-main.ts',
    renderer: 'src/preload-renderer.ts'
  }
})

配置 Schema

HolixConfig

| 字段 | 类型 | 必填 | 默认值 | 描述 | |------|------|------|--------|------| | appID | string | 否 | 'default.app' | 应用 ID，用于区分不同应用 | | app | AppConfig \| null | 否 | null | 单入口应用配置 | | directories | DirectoriesConfig | 否 | { pages: 'src/pages' } | 多页面目录配置 | | preload | PreloadConfig | 否 | null | 预加载脚本配置 | | outDir | string | 否 | 'dist' | 输出目录 | | plugins | string[] | 否 | [] | 插件列表 |

AppConfig

单入口模式配置：

{
  entry: string // 应用入口文件
}

DirectoriesConfig

多页面模式配置：

{
  pages: string | null // 页面目录路径
}

PreloadConfig

预加载脚本配置，支持多种格式：

// 单个文件
preload: 'src/preload.ts'

// 多个文件
preload: ['src/preload1.ts', 'src/preload2.ts']

// 命名映射
preload: {
  main: 'src/preload-main.ts',
  renderer: 'src/preload-renderer.ts'
}

// 不使用预加载
preload: null

配置验证规则

1. app 和 directories 互斥：不能同时定义 app 和 directories
2. 必填字段：app.entry 和 directories.pages 是各自模式下的必填字段
3. 类型检查：所有字段都有严格的类型检查
4. 额外属性：配置对象不允许有未定义的额外属性（使用 .strict()）

API

validateConfig(config)

验证配置对象，返回结果对象（不抛出异常）。

function validateConfig(config: unknown): SafeParseReturnType<unknown, HolixConfig>

parseConfig(config)

解析配置对象，如果无效则抛出 ZodError。

function parseConfig(config: unknown): HolixConfig

mergeConfig(userConfig)

合并用户配置和默认配置。

function mergeConfig(userConfig: Partial<HolixConfig>): HolixConfig

holixConfigSchema

Zod schema 对象，可用于自定义验证。

import { holixConfigSchema } from '@holix/config'

// 扩展 schema
const extendedSchema = holixConfigSchema.extend({
  customField: z.string()
})

错误处理

import { parseConfig } from '@holix/config'
import { ZodError } from 'zod'

try {
  const config = parseConfig({
    app: { entry: 'src/index.ts' },
    directories: { pages: 'src/pages' } // 错误：不能同时定义 app 和 directories
  })
}
catch (error) {
  if (error instanceof ZodError) {
    console.error('Validation errors:')
    error.issues.forEach((issue) => {
      console.error(`- ${issue.path.join('.')}: ${issue.message}`)
    })
  }
}

License

MIT