vitepress-tuck 0.4.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,4 +1,5 @@
 import { DefaultTheme, UserConfig } from "vitepress";
+import { ComponentResolver, Options } from "unplugin-vue-components";
 
 //#region src/types.d.ts
 /**
@@ -81,6 +82,13 @@ 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;
 }
 /**
  * User configuration extension that adds a `plugins` field to VitePress's
@@ -88,13 +96,59 @@ interface VitepressPlugin extends Pick<UserConfig, 'markdown' | 'vite' | 'vue' |
  *
  * 用户配置扩展，为 VitePress 的 `UserConfig` 新增 `plugins` 字段。
  */
-interface PluginsConfig {
+interface TuckConfig {
   /**
    * 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
@@ -144,7 +198,7 @@ interface PluginsConfig {
  * })
  * ```
  */
-declare function defineConfig<ThemeConfig = DefaultTheme.Config>(config: UserConfig<NoInfer<ThemeConfig>> & PluginsConfig): UserConfig<NoInfer<ThemeConfig>>;
+declare function defineConfig<ThemeConfig = DefaultTheme.Config>(config: UserConfig<NoInfer<ThemeConfig>> & TuckConfig): UserConfig<NoInfer<ThemeConfig>>;
 //#endregion
 //#region src/define-plugin.d.ts
 /**
@@ -171,4 +225,4 @@ declare function defineConfig<ThemeConfig = DefaultTheme.Config>(config: UserCon
  */
 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,5 +1,6 @@
-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
 /**
 * Defines a VitePress plugin with type inference.
@@ -27,6 +28,22 @@ 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;
 /**
@@ -111,10 +128,76 @@ const virtualEnhanceAppPlugin = definePlugin((options) => ({
 * @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/hooks.ts
+function createHooks() {
+	return {
+		buildEnd: [],
+		transformHead: [],
+		transformHtml: [],
+		transformPageData: [],
+		postRender: [],
+		markdownConfig: []
+	};
+}
+/**
+* 合并插件钩子，根据不同钩子的特性，确保顺序、入参、出参一致
+* @param hooks - 插件钩子列表
+* @param config - 合并后的配置对象
+*/
+function mergePluginHooks(hooks, config) {
+	const userMarkdownConfig = config.markdown?.config;
+	if (hooks.markdownConfig.length) {
+		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 = 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 = 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);
+			return headConfigs;
+		};
+	}
+	if (hooks.transformHtml.length) {
+		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 = 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 = 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
@@ -165,20 +248,14 @@ function builtinPlugins(options) {
 * ```
 */
 function defineConfig(config) {
-	const hooks = {
-		buildEnd: [],
-		transformHead: [],
-		transformHtml: [],
-		transformPageData: [],
-		postRender: [],
-		markdownConfig: []
-	};
-	const { plugins = [], ...userConfig } = 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`,
@@ -191,7 +268,7 @@ function defineConfig(config) {
 	*/
 	const processPlugins = (plugins) => {
 		plugins.forEach((plugin) => {
-			const { name, client, buildEnd, transformHead, transformHtml, transformPageData, postRender, ...customConfig } = 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({
@@ -199,6 +276,7 @@ function defineConfig(config) {
 					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;
@@ -212,52 +290,24 @@ function defineConfig(config) {
 		});
 	};
 	processPlugins(plugins);
-	processPlugins(builtinPlugins({ enhanceApp }));
+	processPlugins(builtinPlugins({
+		enhanceApp,
+		components
+	}));
 	mergedConfig = mergeConfig(mergedConfig, userConfig);
-	const useMarkdownConfig = mergedConfig.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));
-		};
-	}
-	if (hooks.buildEnd.length) {
-		const buildEnd = mergedConfig.buildEnd;
-		mergedConfig.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 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);
-			return headConfigs;
-		};
-	}
-	if (hooks.transformHtml.length) {
-		const transformHtml = mergedConfig.transformHtml;
-		mergedConfig.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) => {
-			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) => {
-			for (const hook of hooks.postRender) context = await hook(context) || context;
-			return await postRender?.(context) || context;
-		};
-	}
+	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,7 +1,7 @@
 {
   "name": "vitepress-tuck",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Enhance vitepress configuration, provide plugins capability.",
   "author": "pengzhanbo <q942450674@outlook.com> (https://github.com/pengzhanbo/)",
   "license": "MIT",
@@ -33,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",