Preview Hub

一个 Vue 3 插件，用于自动生成组件库和工具库的预览界面。支持 Vite 和 Webpack（Vue CLI）两种构建方案。

特性

• 🚀 自动扫描 - 自动发现指定目录下的组件和工具库文件
• 🎯 动态路由 - 通过路由注入实现预览入口，支持深链接
• 🎨 开箱即用 - 提供完整的预览 UI，包括文件树和预览面板
• 🔧 双构建支持 - 兼容 Vite（import.meta.glob）和 Webpack（require.context）
• 📦 轻量级 - 最小化依赖，仅依赖 Vue 3 和 Vue Router 4
• 🎭 组件预览 - 自动渲染 Vue 组件，展示导出的工具函数

安装

npm install @preview-hub/core vue vue-router

快速开始

1. 基础配置（Vite）

// main.ts
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { createPreviewPlugin } from '@preview-hub/core'
import App from './App.vue'

const router = createRouter({
  history: createWebHistory(),
  routes: []
})

const app = createApp(App)
app.use(createPreviewPlugin({
  rootDir: 'src/components',
  utilsDir: 'src/utils',
  basePath: '/preview',
  router
}))
app.use(router)
app.mount('#app')

2. 基础配置（Vue CLI）

// main.ts
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { createPreviewPlugin } from '@preview-hub/core'
import App from './App.vue'

const router = createRouter({
  history: createWebHistory(),
  routes: []
})

const app = createApp(App)
app.use(createPreviewPlugin({
  rootDir: 'src/components',
  utilsDir: 'src/utils',
  basePath: '/preview',
  router
}))
app.use(router)
app.mount('#app')

3. 访问预览

启动开发服务器后，访问 http://localhost:5173/preview（Vite）或 http://localhost:8080/preview（Vue CLI）

API 文档

createPreviewPlugin(options?)

创建并返回一个 Vue 3 插件。

参数

interface PreviewOptions {
  /**
   * 组件库目录路径
   * @default 'src/components-lib'
   */
  rootDir?: string

  /**
   * 工具库目录路径
   * @default 'src/utils-lib'
   */
  utilsDir?: string

  /**
   * 是否包含工具库扫描
   * @default true
   */
  includeUtils?: boolean

  /**
   * 预览页面的基础路由路径
   * @default '/preview'
   */
  basePath?: string

  /**
   * Vue Router 实例，用于注入预览路由
   */
  router?: Router

  /**
   * 预加载模块映射（可选，用于手动覆盖自动扫描）
   * key 形如 '/src/components/Button.vue'
   */
  modules?: Record<string, any>
}

返回值

返回一个 Vue 3 Plugin 对象，可直接传给 app.use()

示例

import { createPreviewPlugin } from '@preview-hub/core'

const plugin = createPreviewPlugin({
  rootDir: 'src/my-components',
  utilsDir: 'src/my-utils',
  basePath: '/component-preview',
  router
})

app.use(plugin)

导出的类型

// 文件条目
export type FileEntry = {
  path: string
  type?: 'component' | 'utils'
}

// 预览状态（通过 provide/inject 访问）
export interface PreviewState {
  files: FileEntry[]
  pathToModule: Record<string, any>
  rootDir: string
  utilsDir: string
  basePath: string
}

组件导出

如果需要单独使用预览组件，可以从 @preview-hub/core/components 导入：

import { PreviewRoot, PreviewTree, PreviewPane } from '@preview-hub/core/components'

组件说明

• PreviewRoot - 主容器组件，包含侧边栏和主面板
• PreviewTree - 文件树组件，显示可预览的文件列表
• PreviewPane - 预览面板组件，显示选中文件的内容或组件

项目结构要求

预览插件会自动扫描指定目录下的所有 .vue、.js 和 .ts 文件。

推荐的目录结构

src/
├── components/
│   ├── Button.vue
│   ├── Card.vue
│   └── Modal.vue
├── utils/
│   ├── helpers.ts
│   ├── validators.ts
│   └── formatters.ts
└── main.ts

工作原理

Vite / Webpack 项目

插件默认会根据 rootDir / utilsDir 自动扫描对应目录。
如需覆盖自动扫描结果，可显式传入 modules。

最佳实践

1. 组件命名

使用清晰的组件名称，便于在预览中识别：

<!-- ✓ Good -->
<template>
  <button>Click me</button>
</template>

<!-- ✗ Avoid -->
<template>
  <div>Click me</div>
</template>

2. 导出工具函数

确保工具函数有明确的导出：

// ✓ Good
export function formatDate(date: Date): string {
  return date.toLocaleDateString()
}

export function parseJSON(str: string) {
  return JSON.parse(str)
}

// ✗ Avoid
function formatDate(date: Date): string {
  return date.toLocaleDateString()
}

3. 组件 Props 文档

为组件 Props 添加 JSDoc 注释，便于文档生成：

interface ButtonProps {
  /** 按钮文本 */
  label: string
  /** 按钮类型 */
  type?: 'primary' | 'secondary' | 'danger'
  /** 是否禁用 */
  disabled?: boolean
}

常见问题

Q: 如何自定义预览样式？

A: 预览组件使用 scoped styles，你可以通过 CSS 变量或覆盖样式来自定义。

Q: 支持哪些文件类型？

A: 目前支持 .vue、.js 和 .ts 文件。

Q: 如何在生产环境中禁用预览？

A: 只在开发环境中注册插件：

if (import.meta.env.DEV) {
  app.use(createPreviewPlugin({ router }))
}

Q: 预览路由会影响应用的其他路由吗？

A: 不会。预览路由是通过 router.addRoute() 动态注入的，不会影响现有路由。

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！