vue3 + vuepress2 + 企业组件库文档

987 阅读4分钟

原来我有个项目,是vue2的文档,今天想当然vue3应该也容易搞定的,很打脸,今天搞了一天

我的组件库已经写好了,可以编译使用了,今天准备给他加一个文档,基于vue2文档项目完成vue3 文档,基本上抄作业就可以了。

首先 vuepress2 官网有很详细的文档, 一步一步安装,(我还真特意去找了文档,到处没有提是不是vuepress2是不是针对vue3的,最后找到了一处写了,实锤了)

tip 先给结论,好不容易搞好了,但是是基于现在的,后面变了就没什么意义了,我的项目,有兴趣可以看看

doc.jsvue.cn/h5

[](MAuthcode | 移动端组件库 (jsvue.cn))

第一, 在组件库中执行安装命令

npm i vuepress@next

next 这里并不是支持 next.js 的意思,是包的最高版本,当时我也想来的,新的东西问题多,但想着这个东西用的人多,百度搜一下,答案不都有吧

装完只是node_module里多了依赖,啥都没有多

第二, 在目录下创建 docs 文件夹

并在里面创建 .vuepress README.md, 这两个跟1版本一样,

第三, 配置起来,在 .vuepress 里创建config.js 文件

参照2的文档里,再看看api,一条一条配置好,基本大差不差,只是发现怎么2.0.0 到现在几年了,还是beta版本在发,真的不稳定啊

配置文件跟现在的vite一样,配置都用 方法包一层,传入到内部使用,

第四, 路由

目录, 跟一样,建立文件夹, index.md README.md 这两个都是默认文件了,

第五, 引入 组件包

并让项目里可以识别组件名, 要处理 ssr里不使用组件,不然会报错,这个抄了掘金的作业,坑就在这里,22年04发的文章,并只字不提具体版本号,(其实配置文件方式一直在变)

修改`.vuepress`文件夹结构,新增`clientAppEnhance.js`文件(迁移特性Vuepress1中名称为enhanceApp.js),该文件的作用是增强客户端应用

├─.vuepress 
│ └─ config 
│ │ └─ navbar.js 
│ │ └─ sidebar.js 
│ └─ public 
│ │ └─ img 
│ └─ clientAppEnhance.js 
│ └─ config.js

这种官网不再这样了,vuepress@2.0.0-beta.61 版本 文档里写的,是直接简写 client.js

内容也是有变化了

import { defineClientConfig } from '@vuepress/client'
import Watth5UI from '../../packages/index'

export default defineClientConfig({
  enhance({ app, router, siteData }) {
    app.use(Watth5UI)
  },
  setup() {},
  rootComponents: [],
})

第六, demo 演示代码块

原来是引入的 demo-container ,现在作者写了一个 vuepress-plugin-demoblock-plus ,引入的plugins 已经不是直接写 包名的字符串了,

plugins: [
    [
      '@vuepress/plugin-register-components',
      {
        componentsDir: path.resolve(__dirname, './components')
      }
    ],
    [      'vuepress-plugin-demoblock-plus'    ]
 ]

这里最坑,看了 vuepress-plugin-demoblock-plus Readme,作者意思是说,不要用最新版,2.0.0版本不稳点,建议使用 2.0.0-beta.51版本,我安装到这个版本,还是报错,

解决问题

  • 方向一

掘金作者(使用Vuepress搭建基于Vue 3.2的组件库(保姆级教程) - 掘金 (juejin.cn))在评论区里,找到开源的github(github.com/laicengfan/… 自已本地跑起,可以使用,作都使用的 vuepress@2.0.0-beta.39 vuepress-plugin-demoblock-plus@1.5.1

问题我的项目安装成这两个版本,跑起来就是报错,百度里找问题也找不到,难道要我把代码迁移到他这个项目来,不能吧

  • 方向二

vuepress-plugin-demoblock-plus 作者 的文档里,很也找到了他的开源项目,(github.com/xinlei3166/… 真根据他在文档里说的,他使用了vue@3.2.44 vuepress@2.0.0-beta.51 他的项目,我down下来跑,也是可以的,但是我的项目安装成这两个版本,也是报 # Cannot access 'clientConfigs' before initialization 引入报错:Cannot access 'clientConfigs' before initialization · Issue #17 · xinlei3166/vuepress-plugin-demoblock-plus (github.com)

最后在 作者的项目上里,看到一个特别的地方,就是作者手动安装了@vuepress/client 包,并且使用的版本也是51,我查看了node_modules里 看了这个包,居然使用了 2.0.0-beta.pre.1的版本,最后我知道,估计是这里了。

手动安装了包就可以了,现在最新版本是2.0.0-beta.61。 版本一样,教材也没用,最后还是不想躺坑,就尽量别搞新东西。

现在nuxt版本也是,依赖变动非常大,版本经常有问题,而且在网上还没有人解决,

前端从去年起,变化真的大,vue3出了,包的版本都阶梯升级了,很容易就会碰到不能用,大家如果遇到问题了,还是尽量多分享吧,也许你的一篇文章,让别人可以度过一个愉快的周末