Vue UI组件库开发 文档搭建方案选型及组件测试相关咨询

方案1：docs目录独立初始化项目（如Nuxt、VitePress） #

• 优势：
  • 可直接复用文档框架的原生能力，包括MD/MDX解析、自动生成侧边栏、全局搜索、主题切换等通用功能，不需要从零搭建文档的基础能力
  • 依赖和配置完全与组件库隔离，不会出现文档依赖和组件库开发依赖的版本冲突，比如组件库需要兼容Vue 2.7，文档可以直接用Vue 3的生态工具开发
  • 构建部署完全解耦，后续文档上线不需要处理组件库的构建逻辑，单独编译docs目录的产物即可
• 劣势：
  • 需要维护两份package.json，依赖升级、环境配置需要分别处理，有额外的维护成本
  • 本地调试组件时需要先做依赖link，首次配置的流程相对繁琐

方案2：根目录单package.json，docs内直接用createApp实例化 #

• 优势：
  • 所有依赖统一在根目录管理，不需要处理多项目依赖同步、软链配置的问题，维护成本极低
  • 本地调试效率极高，组件源代码修改后可以直接在文档中实时生效，不需要额外走组件库构建、依赖更新的流程
  • 配置轻量化，如果你只需要做基础的组件示例展示、API说明，不需要复杂的文档功能，这个方案可以快速落地
• 劣势：
  • 所有文档相关的能力都需要自行实现，后续如果需要增加搜索、版本管理、国际化这类复杂功能，维护成本会大幅上升
  • 依赖容易出现冲突，组件库的兼容要求会限制文档工具的选型，无法灵活使用新的生态工具

选型建议：如果是面向公开用户的开源组件库，需要完善的文档体验，优先选第一种方案，直接用Vue生态成熟的文档框架即可；如果是内部团队使用的小型组件库，文档需求简单，第二种方案的投入产出比更高

完全可以，这是组件库开发的标准流程，两种文档方案都支持：

• 单package.json的方案：直接在文档的示例代码中引入组件的源文件即可，修改组件代码后文档的示例会同步热更新，边写文档边验证组件的功能、样式是否符合预期
• 独立docs项目的方案：本地开发阶段用包管理工具的link命令，把组件库根目录软链到docs项目的node_modules中，再给组件库开一个构建监听进程，组件代码修改后会自动编译产物同步到docs，文档里的示例也会同步更新

最佳实践：可以在文档的示例中覆盖组件的边界场景，比如空值传入、极端内容长度、多props组合的效果，相当于把文档示例和组件测试用例结合，同时完成文档编写和功能验证的工作

内容的提问来源于stack exchange，提问作者Andrea Verrecchia