vitepress-tuck 0.3.0 → 0.5.0

package/README.md

@@ -1,16 +1,18 @@
-vitepress-tuck
+# vitepress-tuck
 
 Enhance vitepress configuration and provide plugin development capabilities.
 
 > [!NOTE]
-> vitepress itself does not provide complete plugin development capabilities. Some existing slightly complex plugins often need to be configured in both the `markdown` and `vite` sections of the configuration file. The process of integrating plugins in vitepress for users is scattered and difficult to maintain.
+> vitepress itself does not provide complete plugin development capabilities.
+> Some existing slightly complex plugins often need to be configured in both the `markdown` and `vite` sections of the configuration file.
+> The process of integrating plugins in vitepress for users is scattered and difficult to maintain.
 >
 > `tuck` provides vitepress with simple, flexible, and low-barrier plugin development capabilities:
 >
 > - Developers can directly develop plugins using `definePlugin`;
 > - Users only need to add plugins in the `plugins` configuration.
 
-Install
+## Install
 
 ```bash
 # npm
@@ -23,7 +25,7 @@ pnpm add vitepress vitepress-tuck
 yarn add vitepress vitepress-tuck
 ```
 
-Using tuck in vitepress
+## Using tuck in vitepress
 
 Replace `defineConfig` from `vitepress` with `defineConfig` from `vitepress-tuck`
 
@@ -55,7 +57,7 @@ export default {
 } satisfies Theme
 ```
 
-Plugin Development
+## Plugin Development
 
 Develop plugins using `definePlugin`.
 
@@ -97,7 +99,7 @@ Use the `client` field in the `exports` of `package.json` to export client code:
 {
   "exports": {
     ".": "./node/index.js",
-    "client": "./client/index.js"
+    "./client": "./client/index.js"
   }
 }
 ```
@@ -113,3 +115,65 @@ export function enhanceAppWithMyPlugin({ app }: EnhanceAppContext) {
 ```
 
 `vitepress-tuck` will check the `client` configuration and automatically inject the code into `virtual:enhance-app`.
+
+When a plugin provides Vue components that should be auto-imported, declare them via the `componentResolver` field.
+The simplest form is an array of component names — they will be resolved from `<plugin-name>/client`:
+
+```ts
+import { definePlugin } from 'vitepress-tuck'
+
+export default definePlugin(() => ({
+  name: 'vitepress-plugin-my-plugin',
+  // Components listed here are auto-imported from 'vitepress-plugin-my-plugin/client'
+  componentResolver: ['MyComponent', 'OtherComponent'],
+  // ...other config
+}))
+```
+
+For more advanced use cases, you can also pass a custom `ComponentResolver` object from `unplugin-vue-components`:
+
+```ts
+import type { ComponentResolver } from 'unplugin-vue-components'
+import { definePlugin } from 'vitepress-tuck'
+
+const myResolver: ComponentResolver = {
+  type: 'component',
+  resolve: (name) => {
+    if (name.startsWith('My')) {
+      return { name, from: 'vitepress-plugin-my-plugin/client' }
+    }
+  },
+}
+
+export default definePlugin(() => ({
+  name: 'vitepress-plugin-my-plugin',
+  componentResolver: myResolver,
+  // ...other config
+}))
+```
+
+## Auto Components
+
+`vitepress-tuck` integrates [`unplugin-vue-components`](https://github.com/unplugin/unplugin-vue-components) as
+a built-in plugin, enabling automatic on-demand component importing for `.vue` and `.md` files.
+You no longer need to manually import and register components.
+
+By default, the built-in plugin scans `.vue` and `.md` files and generates type declarations
+at `node_modules/.vite/components.d.ts`. You can customize the behavior via the `components` option:
+
+```ts
+// .vitepress/config.ts
+import { defineConfig } from 'vitepress-tuck'
+
+export default defineConfig({
+  components: {
+    // Any unplugin-vue-components options, e.g.:
+    dirs: ['src/components'],
+    directoryAsNamespace: true,
+  },
+  plugins: [],
+})
+```
+
+When a plugin provides Vue components, it can declare them via the `componentResolver` field so that they
+are automatically resolved by `unplugin-vue-components` — see [Plugin Development](#plugin-development).

package/README.zh-CN.md

@@ -95,7 +95,7 @@ export default definePlugin((options?: MyPluginOptions) => ({
 {
   "exports": {
     ".": "./node/index.js",
-    "client": "./client/index.js"
+    "./client": "./client/index.js"
   }
 }
 ```
@@ -111,3 +111,61 @@ export function enhanceAppWithMyPlugin({ app }: EnhanceAppContext) {
 ```
 
 `vitepress-tuck` 会检查 `client` 配置，将代码自动注入到 `virtual:enhance-app` 中。
+
+当插件提供需要自动导入的 Vue 组件时，可通过 `componentResolver` 字段声明。最简单的形式是组件名数组，这些组件会从 `<插件名>/client` 自动解析：
+
+```ts
+import { definePlugin } from 'vitepress-tuck'
+
+export default definePlugin(() => ({
+  name: 'vitepress-plugin-my-plugin',
+  // 此处列出的组件会从 'vitepress-plugin-my-plugin/client' 自动导入
+  componentResolver: ['MyComponent', 'OtherComponent'],
+  // ...其他配置
+}))
+```
+
+对于更复杂的场景，也可以传入来自 `unplugin-vue-components` 的自定义 `ComponentResolver` 对象：
+
+```ts
+import type { ComponentResolver } from 'unplugin-vue-components'
+import { definePlugin } from 'vitepress-tuck'
+
+const myResolver: ComponentResolver = {
+  type: 'component',
+  resolve: (name) => {
+    if (name.startsWith('My')) {
+      return { name, from: 'vitepress-plugin-my-plugin/client' }
+    }
+  },
+}
+
+export default definePlugin(() => ({
+  name: 'vitepress-plugin-my-plugin',
+  componentResolver: myResolver,
+  // ...其他配置
+}))
+```
+
+## 自动组件导入
+
+`vitepress-tuck` 内置集成了 [`unplugin-vue-components`](https://github.com/unplugin/unplugin-vue-components) 插件，
+为 `.vue` 和 `.md` 文件提供自动按需组件导入能力，无需手动 import 和注册组件。
+
+默认情况下，内置插件会扫描 `.vue` 和 `.md` 文件，并在 `node_modules/.vite/components.d.ts` 生成类型声明。你可以通过 `components` 选项自定义行为：
+
+```ts
+// .vitepress/config.ts
+import { defineConfig } from 'vitepress-tuck'
+
+export default defineConfig({
+  components: {
+    // 任意 unplugin-vue-components 选项，例如：
+    dirs: ['src/components'],
+    directoryAsNamespace: true,
+  },
+  plugins: [],
+})
+```
+
+当插件提供 Vue 组件时，可通过 `componentResolver` 字段声明，以便由 `unplugin-vue-components` 自动解析 —— 详见[插件开发](#插件开发)。

package/dist/index.d.ts

@@ -1,23 +1,59 @@
 import { DefaultTheme, UserConfig } from "vitepress";
+import { ComponentResolver, Options } from "unplugin-vue-components";
 
 //#region src/types.d.ts
+/**
+ * Represents a VitePress plugin in the vitepress-tuck ecosystem.
+ *
+ * A plugin extends a subset of VitePress's `UserConfig` fields (markdown, vite,
+ * vue, and lifecycle hooks) and adds a `name` plus an optional `client`
+ * descriptor for automatic client-side injection via the
+ * `virtual:enhance-app` virtual module.
+ *
+ * 表示 vitepress-tuck 生态中的 VitePress 插件。
+ *
+ * 插件扩展了 VitePress `UserConfig` 的部分字段（markdown、vite、vue 及生命周期
+ * 钩子），并新增 `name` 与可选的 `client` 描述符，用于通过
+ * `virtual:enhance-app` 虚拟模块自动注入客户端代码。
+ *
+ * @example
+ * ```ts
+ * export const myPlugin = definePlugin((options?: MyOptions) => ({
+ *   name: 'vitepress-plugin-my',
+ *   markdown: { config: (md) => md.use(myMarkdownPlugin) },
+ *   client: { enhance: true },
+ * }))
+ * ```
+ */
 interface VitepressPlugin extends Pick<UserConfig, 'markdown' | 'vite' | 'vue' | 'buildEnd' | 'transformHead' | 'transformHtml' | 'transformPageData' | 'postRender'> {
   /**
-   * 插件名称
+   * Unique name of the plugin, also used as the client module specifier.
+   *
+   * 插件的唯一名称，同时用作客户端模块标识符。
    */
   name: string;
   /**
-   * 以 import enhanceApp from 'virtual:enhance-app' 注入到客户端代码中。
+   * Client-side injection descriptor consumed by the `virtual:enhance-app` module.
+   *
+   * When set, the built-in virtual plugin generates
+   * `import enhanceApp from 'virtual:enhance-app'` and invokes it inside
+   * `.vitepress/theme/index.ts` via `enhanceApp(ctx)`, so plugin consumers do
+   * not need to wire up client code manually.
+   *
+   * 客户端注入描述符，由 `virtual:enhance-app` 模块消费。
    *
-   * 在 `.vitepress/theme/index.ts` 中调用 enhanceApp(ctx)，
-   * 完成插件的客户端代码的自动注入，插件使用者无需手动添加。
+   * 设置后，内置虚拟插件会生成 `import enhanceApp from 'virtual:enhance-app'`，
+   * 并在 `.vitepress/theme/index.ts` 中通过 `enhanceApp(ctx)` 调用，
+   * 完成插件客户端代码的自动注入，插件使用者无需手动添加。
    */
   client?: {
     /**
-     * 添加自定义的 import 语句.
+     * Custom import statements injected into the generated client module.
+     *
+     * 向生成的客户端模块注入自定义 import 语句。
      *
      * @example
-     * 导入 css 文件
+     * Import a CSS file / 导入 CSS 文件
      * ```ts
      * {
      *   imports: ['import "vitepress-plugin-xxx/styles/index.css"'],
@@ -26,12 +62,16 @@ interface VitepressPlugin extends Pick<UserConfig, 'markdown' | 'vite' | 'vue' |
      */
     imports?: string[];
     /**
+     * Name of the named `enhanceApp` function exported from
+     * `vitepress-plugin-xxx/client`. This function is invoked as
+     * `enhanceApp(ctx)` inside `vitepress/theme/index.ts`.
+     *
      * 插件包 `vitepress-plugin-xxx/client` 中导出的具名 `enhanceApp` 函数名。
-     * 该函数会在 `vitepress/theme/index.ts` 中 的 `enhanceApp(ctx)` 调用。
+     * 该函数会在 `vitepress/theme/index.ts` 中的 `enhanceApp(ctx)` 调用。
      *
-     * - 未设置时，默认不注入 enhanceApp 函数
-     * - 设置为 `true` 时，默认函数名为 `enhanceApp`
-     * - 设置为字符串时，函数名为该字符串
+     * - When unset, no `enhanceApp` function is injected / 未设置时，默认不注入 enhanceApp 函数
+     * - When `true`, the function name defaults to `enhanceApp` / 设置为 `true` 时，默认函数名为 `enhanceApp`
+     * - When a string, that string is used as the function name / 设置为字符串时，函数名为该字符串
      *
      * @example
      * ```ts
@@ -42,21 +82,147 @@ interface VitepressPlugin extends Pick<UserConfig, 'markdown' | 'vite' | 'vue' |
      */
     enhance?: string | boolean;
   };
+  /**
+   * Component resolvers to be used by `unplugin-vue-components` plugin.
+   *
+   * 用于 `unplugin-vue-components` 插件的组件解析器。
+   *
+   */
+  componentResolver?: string[] | ComponentResolver;
 }
-interface PluginsConfig {
+/**
+ * User configuration extension that adds a `plugins` field to VitePress's
+ * `UserConfig`.
+ *
+ * 用户配置扩展，为 VitePress 的 `UserConfig` 新增 `plugins` 字段。
+ */
+interface TuckConfig {
   /**
-   * vitepress 插件
+   * List of vitepress-tuck plugins to be processed by `defineConfig`.
+   *
+   * 由 `defineConfig` 处理的 vitepress-tuck 插件列表。
    */
   plugins?: VitepressPlugin[];
+  /**
+   * Options for `unplugin-vue-components` plugin.
+   *
+   * `unplugin-vue-components` 插件的选项。
+   *
+   * @see - https://github.com/unplugin/unplugin-vue-components
+   */
+  components?: Options;
+}
+/**
+ * Internal collection of lifecycle hooks gathered from all plugins.
+ *
+ * Hooks are grouped by their execution strategy: parallel hooks store an array
+ * of functions that run concurrently, while sequential hooks store an array of
+ * functions that run in order with each receiving the previous result.
+ *
+ * 从所有插件收集的生命周期钩子集合。
+ *
+ * 钩子按执行策略分组：并发类钩子存储并发执行的函数数组，顺序链式类钩子存储
+ * 按顺序执行的函数数组，每个函数接收上一个的结果。
+ */
+interface VitepressPluginHooks {
+  /**
+   * `buildEnd` hooks, executed in parallel / `buildEnd` 钩子，并发执行
+   */
+  buildEnd: NonNullable<UserConfig['buildEnd']>[];
+  /**
+   * `transformHead` hooks, executed in parallel with merged results / `transformHead` 钩子，并发执行并合并结果
+   */
+  transformHead: NonNullable<UserConfig['transformHead']>[];
+  /**
+   * `transformHtml` hooks, executed sequentially with chained results / `transformHtml` 钩子，顺序链式执行
+   */
+  transformHtml: NonNullable<UserConfig['transformHtml']>[];
+  /**
+   * `transformPageData` hooks, executed sequentially with chained results / `transformPageData` 钩子，顺序链式执行
+   */
+  transformPageData: NonNullable<UserConfig['transformPageData']>[];
+  /**
+   * `postRender` hooks, executed sequentially with chained results / `postRender` 钩子，顺序链式执行
+   */
+  postRender: NonNullable<UserConfig['postRender']>[];
+  /**
+   * `markdown.config` hooks, executed in parallel / `markdown.config` 钩子，并发执行
+   */
+  markdownConfig: NonNullable<NonNullable<UserConfig['markdown']>['config']>[];
 }
 //#endregion
 //#region src/define-config.d.ts
-declare function defineConfig<ThemeConfig = DefaultTheme.Config>(config: UserConfig<NoInfer<ThemeConfig>> & PluginsConfig): UserConfig<NoInfer<ThemeConfig>>;
+/**
+ * Defines a VitePress configuration with plugin lifecycle management.
+ *
+ * This is the core function of vitepress-tuck. It accepts a standard VitePress
+ * `UserConfig` extended with a `plugins` field, then iterates over every plugin
+ * to extract client config, lifecycle hooks, and VitePress config fragments.
+ *
+ * Hook merging strategy:
+ * - **Parallel/concurrent**: `markdown.config`, `buildEnd`, `transformHead` run
+ *   via `Promise.all`; `transformHead` results are concatenated.
+ * - **Sequential/chained**: `transformHtml`, `transformPageData`, `postRender`
+ *   run in order, with each hook receiving the previous hook's result.
+ *
+ * User-provided hooks (from `userConfig`) are appended as the final step of
+ * each chain so they always run after plugin hooks. The returned config is a
+ * standard VitePress `UserConfig`, fully compatible with native VitePress.
+ *
+ * 定义带插件生命周期管理的 VitePress 配置。
+ *
+ * 这是 vitepress-tuck 的核心函数。它接收一个扩展了 `plugins` 字段的标准
+ * VitePress `UserConfig`，然后遍历所有插件，提取 client 配置、生命周期钩子和
+ * VitePress 配置片段。
+ *
+ * 钩子合并策略：
+ * - **并发类**：`markdown.config`、`buildEnd`、`transformHead` 通过 `Promise.all`
+ *   并发执行；`transformHead` 的结果会被拼接合并。
+ * - **顺序链式类**：`transformHtml`、`transformPageData`、`postRender` 按顺序执行，
+ *   每个钩子接收上一个钩子的结果。
+ *
+ * 用户提供的钩子（来自 `userConfig`）作为每条链的最后一步追加，确保始终在
+ * 插件钩子之后执行。返回值为标准 VitePress `UserConfig`，完全兼容原生 VitePress。
+ *
+ * @param config - VitePress user config with an optional `plugins` field / 带可选 `plugins` 字段的 VitePress 用户配置
+ * @returns A standard VitePress `UserConfig` with plugin hooks merged in / 合并了插件钩子的标准 VitePress `UserConfig`
+ * @example
+ * ```ts
+ * import { defineConfig } from 'vitepress-tuck'
+ * import { qrcode } from 'vitepress-plugin-qrcode'
+ *
+ * export default defineConfig({
+ *   plugins: [qrcode()],
+ *   title: 'My Site',
+ *   // standard VitePress options...
+ * })
+ * ```
+ */
+declare function defineConfig<ThemeConfig = DefaultTheme.Config>(config: UserConfig<NoInfer<ThemeConfig>> & TuckConfig): UserConfig<NoInfer<ThemeConfig>>;
 //#endregion
 //#region src/define-plugin.d.ts
 /**
- * 提供一种 vitepress 插件的定义方式，简化用户配置的复杂度，将复杂度转移到 vitepress 插件中
+ * Defines a VitePress plugin with type inference.
+ *
+ * This is an identity function that preserves the plugin factory type while
+ * enabling TypeScript to infer the options type `T` from the factory signature.
+ * It simplifies user configuration by moving complexity into the plugin itself.
+ *
+ * 定义 VitePress 插件，提供类型推断。
+ *
+ * 这是一个恒等函数，保留插件工厂类型，同时让 TypeScript 从工厂签名推断选项
+ * 类型 `T`。它将复杂度转移到插件内部，从而简化用户配置。
+ *
+ * @param plugin - Plugin factory function returning a `VitepressPlugin` / 返回 `VitepressPlugin` 的插件工厂函数
+ * @returns The same plugin factory function / 相同的插件工厂函数
+ * @example
+ * ```ts
+ * export const myPlugin = definePlugin((options?: MyOptions) => ({
+ *   name: 'vitepress-plugin-my',
+ *   markdown: { config: (md) => md.use(myMarkdownPlugin) },
+ * }))
+ * ```
  */
 declare function definePlugin<T>(plugin: (options?: T) => VitepressPlugin): (options?: T) => VitepressPlugin;
 //#endregion
-export { PluginsConfig, VitepressPlugin, defineConfig, definePlugin };
+export { TuckConfig, VitepressPlugin, VitepressPluginHooks, defineConfig, definePlugin };

package/dist/index.js

@@ -1,15 +1,77 @@
-import { isString, toTruthy } from "@pengzhanbo/utils";
+import { isArray, isString, toTruthy } from "@pengzhanbo/utils";
 import { mergeConfig } from "vitepress";
+import Components from "unplugin-vue-components/vite";
 //#region src/define-plugin.ts
 /**
-* 提供一种 vitepress 插件的定义方式，简化用户配置的复杂度，将复杂度转移到 vitepress 插件中
+* Defines a VitePress plugin with type inference.
+*
+* This is an identity function that preserves the plugin factory type while
+* enabling TypeScript to infer the options type `T` from the factory signature.
+* It simplifies user configuration by moving complexity into the plugin itself.
+*
+* 定义 VitePress 插件，提供类型推断。
+*
+* 这是一个恒等函数，保留插件工厂类型，同时让 TypeScript 从工厂签名推断选项
+* 类型 `T`。它将复杂度转移到插件内部，从而简化用户配置。
+*
+* @param plugin - Plugin factory function returning a `VitepressPlugin` / 返回 `VitepressPlugin` 的插件工厂函数
+* @returns The same plugin factory function / 相同的插件工厂函数
+* @example
+* ```ts
+* export const myPlugin = definePlugin((options?: MyOptions) => ({
+*   name: 'vitepress-plugin-my',
+*   markdown: { config: (md) => md.use(myMarkdownPlugin) },
+* }))
+* ```
 */
 function definePlugin(plugin) {
 	return plugin;
 }
 //#endregion
+//#region src/builtin-plugins/auto-components.ts
+const autoComponentsPlugin = definePlugin((options) => ({
+	name: "auto-components",
+	vite: { plugins: [Components({
+		dts: "node_modules/.vite/components.d.ts",
+		include: [
+			/\.vue$/,
+			/\.vue\?vue/,
+			/\.vue\.[tj]sx?\?vue/,
+			/\.md$/,
+			/\.md\?import/
+		],
+		...options
+	})] }
+}));
+//#endregion
 //#region src/builtin-plugins/virtual-enhance-app.ts
 let uuid = 0;
+/**
+* Creates a Vite virtual module plugin that generates the
+* `virtual:enhance-app` module on the fly.
+*
+* The generated module imports every plugin's client entry and chains their
+* `enhanceApp(ctx)` calls inside a single default export. Users import this
+* module once in `.vitepress/theme/index.ts` to activate all plugin client
+* side effects.
+*
+* 创建 Vite 虚拟模块插件，动态生成 `virtual:enhance-app` 模块。
+*
+* 生成的模块导入每个插件的客户端入口，并在单个默认导出中链式调用它们的
+* `enhanceApp(ctx)`。用户在 `.vitepress/theme/index.ts` 中导入该模块一次，
+* 即可激活所有插件的客户端副作用。
+*
+* @param options - Options describing imports and enhance functions / 描述导入与 enhance 函数的选项
+* @returns A Vite `Plugin` instance / Vite `Plugin` 实例
+* @example
+* `Generated module (conceptual)`:
+* ```ts
+* import { enhanceApp as enhanceApp$0 } from 'vitepress-plugin-foo/client'
+* export default function enhanceApp(ctx) {
+*  enhanceApp$0(ctx)
+* }
+* ```
+*/
 function virtualEnhanceApp(options) {
 	const moduleId = "virtual:enhance-app";
 	const resolveId = `\0${moduleId}`;
@@ -36,22 +98,49 @@ ${enhanceCode.join("\n")}
 		}
 	};
 }
+/**
+* Plugin factory wrapping `virtualEnhanceApp` as a vitepress-tuck plugin.
+*
+* 将 `virtualEnhanceApp` 包装为 vitepress-tuck 插件的工厂函数。
+*
+* @param options - Options forwarded to `virtualEnhanceApp` / 转发给 `virtualEnhanceApp` 的选项
+* @returns A `VitepressPlugin` that registers the virtual module / 注册虚拟模块的 `VitepressPlugin`
+*/
 const virtualEnhanceAppPlugin = definePlugin((options) => ({
 	name: "virtual-enhance-app",
 	vite: { plugins: [virtualEnhanceApp(options || {})] }
 }));
 //#endregion
 //#region src/builtin-plugins/index.ts
+/**
+* Returns the list of built-in plugins shipped with vitepress-tuck.
+*
+* Currently includes the `virtual:enhance-app` Vite plugin (for client code
+* injection) and a `vitepress-tuck:deps` plugin that marks
+* `vitepress-plugin-toolkit` as SSR non-external.
+*
+* 返回 vitepress-tuck 自带的内置插件列表。
+*
+* 当前包含用于客户端代码注入的 `virtual:enhance-app` Vite 插件，以及将
+* `vitepress-plugin-toolkit` 标记为 SSR 非外部依赖的 `vitepress-tuck:deps` 插件。
+*
+* @param options - Options for built-in plugin construction / 内置插件构建选项
+* @returns Array of built-in `VitepressPlugin` instances / 内置 `VitepressPlugin` 实例数组
+*/
 function builtinPlugins(options) {
-	return [virtualEnhanceAppPlugin(options.enhanceApp), () => ({
-		name: "vitepress-tuck:deps",
-		vite: { ssr: { noExternal: ["vitepress-plugin-toolkit"] } }
-	})];
+	return [
+		virtualEnhanceAppPlugin(options.enhanceApp),
+		autoComponentsPlugin(options.components),
+		() => ({
+			name: "vitepress-tuck:deps",
+			vite: { ssr: { noExternal: ["vitepress-plugin-toolkit"] } }
+		})
+	];
 }
 //#endregion
-//#region src/define-config.ts
-function defineConfig(config) {
-	const hooks = {
+//#region src/hooks.ts
+function createHooks() {
+	return {
 		buildEnd: [],
 		transformHead: [],
 		transformHtml: [],
@@ -59,53 +148,29 @@ function defineConfig(config) {
 		postRender: [],
 		markdownConfig: []
 	};
-	const { plugins = [], ...userConfig } = config;
-	let mergedConfig = {};
-	const enhanceApp = {
-		imports: [],
-		enhances: []
-	};
-	const processPlugins = (plugins) => {
-		plugins.forEach((plugin) => {
-			const { name, client, buildEnd, transformHead, transformHtml, transformPageData, postRender, ...customConfig } = plugin;
-			if (client) {
-				client.imports?.length && enhanceApp.imports.push(...client.imports);
-				client.enhance && enhanceApp.enhances.push({
-					moduleName: name,
-					exportName: isString(client.enhance) ? client.enhance : "enhanceApp"
-				});
-			}
-			if (customConfig.markdown?.config) {
-				hooks.markdownConfig.push(customConfig.markdown.config);
-				delete customConfig.markdown.config;
-			}
-			buildEnd && hooks.buildEnd.push(buildEnd);
-			transformHead && hooks.transformHead.push(transformHead);
-			transformHtml && hooks.transformHtml.push(transformHtml);
-			transformPageData && hooks.transformPageData.push(transformPageData);
-			postRender && hooks.postRender.push(postRender);
-			mergedConfig = mergeConfig(mergedConfig, customConfig);
-		});
-	};
-	processPlugins(plugins);
-	processPlugins(builtinPlugins({ enhanceApp }));
-	mergedConfig = mergeConfig(mergedConfig, userConfig);
-	const useMarkdownConfig = mergedConfig.markdown?.config;
+}
+/**
+* 合并插件钩子，根据不同钩子的特性，确保顺序、入参、出参一致
+* @param hooks - 插件钩子列表
+* @param config - 合并后的配置对象
+*/
+function mergePluginHooks(hooks, config) {
+	const userMarkdownConfig = config.markdown?.config;
 	if (hooks.markdownConfig.length) {
-		mergedConfig.markdown ??= {};
-		mergedConfig.markdown.config = async (md) => {
-			await Promise.all([...hooks.markdownConfig.map((config) => config(md)), useMarkdownConfig?.(md)].filter(toTruthy));
+		config.markdown ??= {};
+		config.markdown.config = async (md) => {
+			await Promise.all([...hooks.markdownConfig.map((config) => config(md)), userMarkdownConfig?.(md)].filter(toTruthy));
 		};
 	}
 	if (hooks.buildEnd.length) {
-		const buildEnd = mergedConfig.buildEnd;
-		mergedConfig.buildEnd = async (site) => {
+		const buildEnd = config.buildEnd;
+		config.buildEnd = async (site) => {
 			await Promise.all([...hooks.buildEnd.map((hook) => hook(site)), buildEnd?.(site)].filter(toTruthy));
 		};
 	}
 	if (hooks.transformHead.length) {
-		const transformHead = mergedConfig.transformHead;
-		mergedConfig.transformHead = async (site) => {
+		const transformHead = config.transformHead;
+		config.transformHead = async (site) => {
 			const result = await Promise.all([...hooks.transformHead.map((hook) => hook(site)), transformHead?.(site)].filter(toTruthy));
 			const headConfigs = [];
 			for (const item of result) item && headConfigs.push(...item);
@@ -113,27 +178,136 @@ function defineConfig(config) {
 		};
 	}
 	if (hooks.transformHtml.length) {
-		const transformHtml = mergedConfig.transformHtml;
-		mergedConfig.transformHtml = async (code, id, ctx) => {
+		const transformHtml = config.transformHtml;
+		config.transformHtml = async (code, id, ctx) => {
 			for (const hook of hooks.transformHtml) code = await hook(code, id, ctx) || code;
 			return await transformHtml?.(code, id, ctx) || code;
 		};
 	}
 	if (hooks.transformPageData.length) {
-		const transformPageData = mergedConfig.transformPageData;
-		mergedConfig.transformPageData = async (pageData, ctx) => {
+		const transformPageData = config.transformPageData;
+		config.transformPageData = async (pageData, ctx) => {
 			for (const hook of hooks.transformPageData) pageData = await hook(pageData, ctx) || pageData;
 			return await transformPageData?.(pageData, ctx) || pageData;
 		};
 	}
 	if (hooks.postRender.length) {
-		const postRender = mergedConfig.postRender;
-		mergedConfig.postRender = async (context) => {
+		const postRender = config.postRender;
+		config.postRender = async (context) => {
 			for (const hook of hooks.postRender) context = await hook(context) || context;
 			return await postRender?.(context) || context;
 		};
 	}
+}
+//#endregion
+//#region src/define-config.ts
+/**
+* Defines a VitePress configuration with plugin lifecycle management.
+*
+* This is the core function of vitepress-tuck. It accepts a standard VitePress
+* `UserConfig` extended with a `plugins` field, then iterates over every plugin
+* to extract client config, lifecycle hooks, and VitePress config fragments.
+*
+* Hook merging strategy:
+* - **Parallel/concurrent**: `markdown.config`, `buildEnd`, `transformHead` run
+*   via `Promise.all`; `transformHead` results are concatenated.
+* - **Sequential/chained**: `transformHtml`, `transformPageData`, `postRender`
+*   run in order, with each hook receiving the previous hook's result.
+*
+* User-provided hooks (from `userConfig`) are appended as the final step of
+* each chain so they always run after plugin hooks. The returned config is a
+* standard VitePress `UserConfig`, fully compatible with native VitePress.
+*
+* 定义带插件生命周期管理的 VitePress 配置。
+*
+* 这是 vitepress-tuck 的核心函数。它接收一个扩展了 `plugins` 字段的标准
+* VitePress `UserConfig`，然后遍历所有插件，提取 client 配置、生命周期钩子和
+* VitePress 配置片段。
+*
+* 钩子合并策略：
+* - **并发类**：`markdown.config`、`buildEnd`、`transformHead` 通过 `Promise.all`
+*   并发执行；`transformHead` 的结果会被拼接合并。
+* - **顺序链式类**：`transformHtml`、`transformPageData`、`postRender` 按顺序执行，
+*   每个钩子接收上一个钩子的结果。
+*
+* 用户提供的钩子（来自 `userConfig`）作为每条链的最后一步追加，确保始终在
+* 插件钩子之后执行。返回值为标准 VitePress `UserConfig`，完全兼容原生 VitePress。
+*
+* @param config - VitePress user config with an optional `plugins` field / 带可选 `plugins` 字段的 VitePress 用户配置
+* @returns A standard VitePress `UserConfig` with plugin hooks merged in / 合并了插件钩子的标准 VitePress `UserConfig`
+* @example
+* ```ts
+* import { defineConfig } from 'vitepress-tuck'
+* import { qrcode } from 'vitepress-plugin-qrcode'
+*
+* export default defineConfig({
+*   plugins: [qrcode()],
+*   title: 'My Site',
+*   // standard VitePress options...
+* })
+* ```
+*/
+function defineConfig(config) {
+	const hooks = createHooks();
+	const { plugins = [], components = {}, ...userConfig } = config;
+	let mergedConfig = {};
+	const enhanceApp = {
+		imports: [],
+		enhances: []
+	};
+	components.resolvers ??= [];
+	/**
+	* Iterates a list of plugins, extracting client config, lifecycle hooks, and
+	* VitePress config fragments into the shared accumulators (`hooks`,
+	* `enhanceApp`, `mergedConfig`).
+	*
+	* 遍历插件列表，将 client 配置、生命周期钩子和 VitePress 配置片段提取到
+	* 共享累加器（`hooks`、`enhanceApp`、`mergedConfig`）中。
+	*
+	* @param plugins - Plugins to process / 待处理的插件列表
+	*/
+	const processPlugins = (plugins) => {
+		plugins.forEach((plugin) => {
+			const { name, client, componentResolver, buildEnd, transformHead, transformHtml, transformPageData, postRender, ...customConfig } = plugin;
+			if (client) {
+				client.imports?.length && enhanceApp.imports.push(...client.imports);
+				client.enhance && enhanceApp.enhances.push({
+					moduleName: name,
+					exportName: isString(client.enhance) ? client.enhance : "enhanceApp"
+				});
+			}
+			componentResolver && components.resolvers.push(normalizeComponentResolver(name, componentResolver));
+			if (customConfig.markdown?.config) {
+				hooks.markdownConfig.push(customConfig.markdown.config);
+				delete customConfig.markdown.config;
+			}
+			buildEnd && hooks.buildEnd.push(buildEnd);
+			transformHead && hooks.transformHead.push(transformHead);
+			transformHtml && hooks.transformHtml.push(transformHtml);
+			transformPageData && hooks.transformPageData.push(transformPageData);
+			postRender && hooks.postRender.push(postRender);
+			mergedConfig = mergeConfig(mergedConfig, customConfig);
+		});
+	};
+	processPlugins(plugins);
+	processPlugins(builtinPlugins({
+		enhanceApp,
+		components
+	}));
+	mergedConfig = mergeConfig(mergedConfig, userConfig);
+	mergePluginHooks(hooks, mergedConfig);
 	return mergedConfig;
 }
+function normalizeComponentResolver(pluginName, componentResolver) {
+	return isArray(componentResolver) ? {
+		type: "component",
+		resolve: (componentName) => {
+			if (componentResolver.includes(componentName)) return {
+				name: componentName,
+				from: `${pluginName}/client`
+			};
+		}
+	} : componentResolver;
+}
 //#endregion
 export { defineConfig, definePlugin };

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "vitepress-tuck",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Enhance vitepress configuration, provide plugins capability.",
   "author": "pengzhanbo <q942450674@outlook.com> (https://github.com/pengzhanbo/)",
   "license": "MIT",
+  "homepage": "https://tuck.pengzhanbo.cn/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pengzhanbo/vitepress-tuck.git",
     "directory": "packages/vitepress-tuck"
   },
+  "bugs": {
+    "url": "https://github.com/pengzhanbo/vitepress-tuck/issues"
+  },
   "keywords": [
     "vitepress",
     "vitepress-plugin"
@@ -29,7 +33,8 @@
     "vitepress": "^1.6.4 || ^2.0.0-alpha.17"
   },
   "dependencies": {
-    "@pengzhanbo/utils": "^3.7.3"
+    "@pengzhanbo/utils": "^3.7.3",
+    "unplugin-vue-components": "^32.1.0"
   },
   "publishConfig": {
     "access": "public",