@quiteer/vite 0.0.1

package/index.ts

@@ -0,0 +1,106 @@
+import type { UserConfig as TsdownUserConfig } from 'tsdown'
+import type { UserConfig as ViteUserConfig } from 'vite'
+import type { QviteConfig, QviteConfigExport, QviteConfigFnObject } from './src/typings'
+import { defineConfig as tsdownDefineConfig } from 'tsdown'
+import { defineConfig as viteDefineConfig } from 'vite'
+
+export type * from './src/typings'
+
+/**
+ * `@quiteer/vite` 配置声明函数（类型辅助）
+ *
+ * 为 `qvite.config.ts` 提供强类型提示，支持对象、Promise 与函数多种导出形式
+ *
+ * @param config - 可为对象、Promise 或按环境返回配置的函数
+ * @returns 与入参同构的配置对象/函数，用于类型推断，无运行时副作用
+ * @throws {TypeError} 不抛出异常（纯类型辅助），运行时直接返回
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'qvite'
+ * export default defineConfig({ mode: 'development', vite: { plugins: [] } })
+ * ```
+ *
+ * @remarks
+ * - 函数重载覆盖对象、Promise、函数等场景
+ * - 仅用于 TS 类型推断，运行时原样返回
+ *
+ * @security
+ * 不读取文件、不处理敏感信息
+ *
+ * @performance
+ * 常量时间返回，无额外开销
+ */
+export function defineConfig(config: QviteConfig): QviteConfig
+
+export function defineConfig(config: Promise<QviteConfig>): Promise<QviteConfig>
+
+export function defineConfig(config: QviteConfigFnObject): QviteConfigFnObject
+
+export function defineConfig(config: QviteConfigExport): QviteConfigExport
+
+export function defineConfig(config: QviteConfigExport): QviteConfigExport {
+  return config
+}
+
+// 类型导出通过 dts 文件与 typesVersions 提供，避免在 JS 解析阶段出现命名导出未定义的问题
+
+/**
+ * 暴露 Vite 的 `defineConfig`（类型辅助包装）
+ *
+ * 为 Vite 配置文件提供强类型提示；内部委托给 `vite.defineConfig`
+ *
+ * @param config - Vite 配置对象或按环境返回配置的函数
+ * @returns 与入参同构的配置对象/函数，用于类型推断
+ *
+ * @example
+ * ```ts
+ * import { defineViteConfig } from 'qvite'
+ * export default defineViteConfig({ plugins: [] })
+ * ```
+ *
+ * @remarks
+ * - 纯类型辅助，运行时直接委托给 Vite 的 `defineConfig`
+ *
+ * @security
+ * 无敏感信息处理
+ *
+ * @performance
+ * 常量时间委托，无额外开销
+ */
+export function defineViteConfig(
+  config: Parameters<typeof viteDefineConfig>[0]
+): ReturnType<typeof viteDefineConfig> {
+  return viteDefineConfig(config as ViteUserConfig)
+}
+
+/**
+ * 暴露 tsdown 的 `defineConfig`（类型辅助包装）
+ *
+ * 为 tsdown 配置文件提供强类型提示；内部委托给 `tsdown.defineConfig`
+ *
+ * @param config - tsdown 配置对象或配置数组
+ * @returns 与入参同构的配置对象/数组，用于类型推断
+ *
+ * @example
+ * ```ts
+ * import { defineTsdownConfig } from 'qvite'
+ * export default defineTsdownConfig([
+ *   { name: 'client', entry: ['src/index.ts'], outDir: 'dist/client', platform: 'node' }
+ * ])
+ * ```
+ *
+ * @remarks
+ * - 纯类型辅助，运行时直接委托给 tsdown 的 `defineConfig`
+ *
+ * @security
+ * 无敏感信息处理
+ *
+ * @performance
+ * 常量时间委托，无额外开销
+ */
+export function defineTsdownConfig(
+  config: Parameters<typeof tsdownDefineConfig>[0]
+): ReturnType<typeof tsdownDefineConfig> {
+  return tsdownDefineConfig(config as TsdownUserConfig | TsdownUserConfig[])
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@quiteer/vite",
+  "type": "module",
+  "version": "0.0.1",
+  "packageManager": "pnpm@10.20.0",
+  "description": "在 vite 的基础上增强的前端架构 cli",
+  "author": "quiteer",
+  "license": "ISC",
+  "homepage": "https://quiteerjs.github.io/web/ci/qvite.html",
+  "keywords": [
+    "vite",
+    "cli"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./src/*"
+      ]
+    }
+  },
+  "bin": {
+    "qvite": "./dist/bin/qvite.mjs"
+  },
+  "scripts": {
+    "dev": "tsdown -w",
+    "build": "tsdown",
+    "release": "qui r --tag-prefix qvite && qui gc && tsdown && pnpm publish"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@quiteer/is": "workspace:*",
+    "@quiteer/parser-config": "^1.0.3",
+    "@quiteer/scripts": "workspace:*",
+    "@quiteer/utils": "workspace:*",
+    "@quiteer/vite-plugins": "workspace:^",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^24.10.1",
+    "c12": "3.3.2",
+    "cac": "6.7.14",
+    "fs-extra": "^11.3.2",
+    "kolorist": "1.8.0",
+    "portfinder": "^1.0.38",
+    "semver": "^7.6.3",
+    "vite": "npm:rolldown-vite@7.2.2",
+    "zx": "^8.8.5"
+  }
+}

package/src/build.ts

@@ -0,0 +1,43 @@
+import type { QviteConfig } from './typings'
+import { build as viteBuild } from 'vite'
+
+import { normalizeConfig, toViteInlineConfig } from './transform'
+
+/**
+ * 执行构建流程（生产模式）
+ *
+ * 先构建 tsdown 产物（若配置提供），再调用 Vite 的 `build` 完成前端打包
+ *
+ * @param options - Qvite 配置对象，含 `vite` 与 `tsdown` 等子配置
+ * @returns Promise<void> 构建完成无返回值
+ * @throws {Error} 当 Vite 或 tsdown 构建失败时抛出异常
+ *
+ * @example
+ * ```ts
+ * await build({ mode: 'production', minify: true, vite: { build: { outDir: 'dist' } } })
+ * ```
+ *
+ * @remarks
+ * - `minify` 会映射为 Vite 的 `build.minify`
+ * - 若 `tsdown` 配置存在，则会先执行 `tsdownBuild`
+ *
+ * @security
+ * 不写入敏感信息，仅调用编译器
+ *
+ * @performance
+ * 构建性能取决于 Vite/tsdown 自身实现
+ */
+export async function build(options: QviteConfig): Promise<void> {
+  const normalized = await normalizeConfig(options)
+
+  if (normalized.tsdown && (
+    (Array.isArray(normalized.tsdown) && normalized.tsdown.length > 0)
+    || (!Array.isArray(normalized.tsdown) && Object.keys(normalized.tsdown).length > 0)
+  )) {
+    const { build: tsdownBuild } = await import('tsdown') as any
+    await tsdownBuild(normalized.tsdown as any)
+  }
+
+  const inline = await toViteInlineConfig(normalized)
+  await viteBuild(inline)
+}

package/src/defaults.ts

@@ -0,0 +1,36 @@
+import type { QviteConfig } from './typings'
+import { fileURLToPath } from 'node:url'
+
+export const defaultOptions = {
+  plugins: {
+    Vue: [{ customElement: true }],
+    UnoCSS: false,
+    VueDevTools: [{}],
+    VueJsx: [{}],
+    Progress: [{}],
+    FileChangeLogger: [{}],
+    RemoveConsole: [{}],
+    MockRouter: [{}]
+  },
+  html: {
+
+  },
+  env: {
+    obfuscate: false,
+    requiredKeys: ['desc']
+  },
+  vite: {
+    server: {
+      port: 3000,
+      strictPort: false
+    },
+    resolve: {
+      alias: {
+        '@': fileURLToPath(new URL('./src', import.meta.url))
+      }
+    },
+    build: {
+      minify: false
+    }
+  }
+} satisfies QviteConfig

package/src/getConfig.ts

@@ -0,0 +1,52 @@
+import type { Command, Mode, QviteConfig, QviteConfigFn } from './typings'
+import { join } from 'node:path'
+import { isFunction } from '@quiteer/is'
+import { parserConfig } from '@quiteer/parser-config'
+import { deepMerge } from '@quiteer/utils'
+import { pathExists } from 'fs-extra'
+import { loadEnv } from 'vite'
+import { store } from './store'
+
+const NOT_FOUND = '找不到 qvite.config.ts | qvite.config.js | qvite.config.json , 请在根目录下添加配置文件 , 或显式的指定配置文件路径（相对于根目录）'
+const PARSING_FAILED = '找到了配置文件,但解析配置文件失败！'
+
+const root = store.get('root') as string
+
+async function configPath(filePath: string) {
+  if (filePath)
+    return join(root, filePath)
+
+  const configList = ['ts', 'mjs', 'cjs', 'js'].map(suffix => `${join(root, 'qvite.config')}.${suffix}`)
+
+  const index = (await Promise.all(configList.map(path => pathExists(path)))).findIndex(flag => flag)
+
+  if (index > -1)
+    return configList[index]
+
+  throw new Error(NOT_FOUND)
+}
+
+export async function getConfig(filePath: string): Promise<QviteConfig> {
+  const path = await configPath(filePath)
+
+  const command = store.get<Command>('command')!
+  const mode = store.get<Mode>('mode')!
+  const modeEnv = loadEnv(mode, root, store.get<string[]>('prefixes')!)
+  const defaultEnv = loadEnv('', root, store.get<string[]>('prefixes')!)
+
+  const env = deepMerge({}, defaultEnv, modeEnv)
+  try {
+    const option: QviteConfig = await parserConfig(path, 'qvite.config')
+
+    if (isFunction(option)) {
+      const configFn = option as QviteConfigFn
+      return configFn({ command, mode, env, root })
+    }
+
+    return option
+  }
+  catch (error) {
+    console.error('error :>> ', error)
+    throw new Error(PARSING_FAILED)
+  }
+}

package/src/plugins.ts

@@ -0,0 +1,14 @@
+import type { PluginOption } from 'vite'
+import type { QvitePlugins } from './typings'
+import { fileChangeLoggerPlugin, mockRouterPlugin, Progress, removeConsolePlugin, UnoCSS, Vue, VueDevTools, VueJsx } from '@quiteer/vite-plugins'
+
+export default {
+  FileChangeLogger: fileChangeLoggerPlugin,
+  MockRouter: mockRouterPlugin,
+  RemoveConsole: removeConsolePlugin,
+  Progress,
+  Vue,
+  VueDevTools,
+  VueJsx,
+  UnoCSS
+} satisfies Record<keyof QvitePlugins, (...args: any[]) => PluginOption>

package/src/store.ts

@@ -0,0 +1,13 @@
+import { cwd } from 'node:process'
+import { PersistentStore } from '@quiteer/utils'
+
+export const store = PersistentStore.getInstance('qvite')
+
+store.set('root', cwd())
+store.set('command', 'serve')
+store.set('config', 'qvite.config.ts')
+store.set('mode', 'development')
+store.set('env', {})
+store.set('minify', false)
+store.set('port', 8080)
+store.set('prefixes', ['QVITE_', 'VITE_'])

package/src/transform.ts

@@ -0,0 +1,50 @@
+import type { InlineConfig, Plugin } from 'vite'
+import type { QviteConfig, QvitePlugins } from './typings'
+import { deepMerge } from '@quiteer/utils'
+import { envConfigPlugin, virtualHtmlPlugin } from '@quiteer/vite-plugins'
+import { mergeConfig } from 'vite'
+import { defaultOptions } from './defaults'
+import defaultPlugins from './plugins'
+import { store } from './store'
+
+type NormalizeConfig = Required<QviteConfig>
+
+export async function normalizeConfig(raw: QviteConfig): Promise<NormalizeConfig> {
+  const config = deepMerge<QviteConfig>(defaultOptions, raw) as NormalizeConfig
+  return config
+}
+
+export function geVitePlugins(config: NormalizeConfig) {
+  const { html, env, plugins } = config
+
+  const pluginKeys = Object.keys(plugins) as (keyof QvitePlugins)[]
+
+  const vitePlugins = pluginKeys.map((key) => {
+    const pluginOptions = plugins[key]
+
+    const pluginFn = defaultPlugins[key] as (...args: any[]) => Plugin
+
+    if (Array.isArray(pluginOptions)) {
+      return pluginFn(...pluginOptions as any[])
+    }
+
+    return null
+  }).filter(Boolean) as Plugin[]
+  return [...vitePlugins, virtualHtmlPlugin(html), envConfigPlugin(env)]
+}
+
+export async function toViteInlineConfig(config: NormalizeConfig): Promise<InlineConfig> {
+  const mode = store.get<string>('mode')!
+  const root = store.get<string>('root')!
+
+  const plugins = geVitePlugins(config)
+
+  const inline: InlineConfig = mergeConfig({
+    configFile: false,
+    root,
+    mode,
+    plugins
+  }, { ...config.vite })
+
+  return inline
+}

package/src/typings.ts

@@ -0,0 +1,48 @@
+import type { EnvConfigPluginOptions, fileChangeLoggerPlugin, mockRouterPlugin, Progress, removeConsolePlugin, UnoCSS, VirtualHtmlOptions, Vue, VueDevTools, VueJsx } from '@quiteer/vite-plugins'
+import type { UserConfig } from 'tsdown'
+import type { UserConfig as ViteUserConfig } from 'vite'
+
+export type { EnvConfig } from '@quiteer/vite-plugins'
+
+export type PluginOptions<T extends (...args: any) => any> = boolean | Parameters<T>
+
+export interface QvitePlugins {
+  Vue?: PluginOptions<typeof Vue>
+  UnoCSS?: PluginOptions<typeof UnoCSS>
+  VueJsx?: PluginOptions<typeof VueJsx>
+  Progress?: PluginOptions<typeof Progress>
+  VueDevTools?: PluginOptions<typeof VueDevTools>
+  RemoveConsole?: PluginOptions<typeof removeConsolePlugin>
+  MockRouter?: PluginOptions<typeof mockRouterPlugin>
+  FileChangeLogger?: PluginOptions<typeof fileChangeLoggerPlugin>
+}
+
+export interface QviteConfig {
+  vite?: ViteUserConfig
+  tsdown?: UserConfig | UserConfig[]
+  plugins?: QvitePlugins
+  html?: VirtualHtmlOptions
+  env?: EnvConfigPluginOptions
+}
+
+export type Mode = 'development' | 'production' | 'test' | 'staging' | 'production' | string
+
+export type Command = 'build' | 'serve'
+
+export interface ConfigEnv<T = Record<string, string>> {
+  command: Command
+  mode: Mode
+  env: T
+  root: string
+}
+
+export type QviteConfigFnObject = (env: ConfigEnv) => QviteConfig
+export type QviteConfigFnPromise = (env: ConfigEnv) => Promise<QviteConfig>
+export type QviteConfigFn = (env: ConfigEnv) => QviteConfig | Promise<QviteConfig>
+
+export type QviteConfigExport
+  = | QviteConfig
+    | Promise<QviteConfig>
+    | QviteConfigFnObject
+    | QviteConfigFnPromise
+    | QviteConfigFn

package/src/watch.ts

@@ -0,0 +1,60 @@
+import type { QviteConfig } from './typings'
+import { getPortPromise } from 'portfinder'
+import { createServer } from 'vite'
+import { store } from './store'
+import { normalizeConfig, toViteInlineConfig } from './transform'
+
+/**
+ * 启动开发服务器（热更新）
+ *
+ * 根据规范化配置启动 Vite Dev Server，自动选择可用端口，并打印访问地址
+ *
+ * @param options - Qvite 配置对象，包含 `vite` 与 `tsdown`
+ * @returns Promise<void>
+ * @throws {Error} 当端口查找或 Vite 启动失败时抛出异常
+ *
+ * @example
+ * ```ts
+ * await watch({ port: 3000, vite: { plugins: [] } })
+ * ```
+ *
+ * @remarks
+ * - 若配置的 `port` 被占用，将自动选取下一个可用端口
+ * - 启动前执行一次 tsdown 构建，便于开发期产物可用
+ *
+ * @security
+ * 不暴露敏感信息，仅打印本地 URL
+ *
+ * @performance
+ * 端口探测为 O(1) 近似成本，服务性能由 Vite 决定
+ */
+export async function watch(options: QviteConfig): Promise<void> {
+  const normalized = await normalizeConfig(options)
+  const port = normalized.vite?.server?.port || store.get<number>('port')!
+
+  const p = await getPortPromise({
+    port
+  })
+
+  store.set('port', p)
+
+  const inline = await toViteInlineConfig(normalized)
+
+  const viteDevServer = await createServer({
+    ...inline,
+    server: { ...inline.server, port: p }
+  })
+
+  await viteDevServer.listen(p)
+  viteDevServer.printUrls()
+
+  if (normalized.tsdown) {
+    const { build: tsdownBuild } = await import('tsdown')
+    if (!Array.isArray(normalized.tsdown)) {
+      await tsdownBuild(normalized.tsdown)
+    }
+    else {
+      await Promise.all(normalized.tsdown.map(tsdownBuild))
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "jsx": "preserve",
+    "lib": ["DOM", "ESNext"],
+    "baseUrl": ".",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "resolveJsonModule": true,
+    "types": ["node"],
+    "strict": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "outDir": "./dist",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*", "typings/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsdown.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'tsdown'
+
+export default defineConfig([
+  {
+    name: 'qvite-api',
+    outDir: 'dist',
+    entry: ['index.ts'],
+    platform: 'node',
+    minify: false,
+    dts: true
+  },
+  {
+    name: 'qvite-cli',
+    outDir: 'dist/bin',
+    platform: 'node',
+    dts: false,
+    minify: false,
+    entry: { qvite: 'cli.ts' }
+  }
+])