前言
本文旨在给大家提供一种构建一个完整 UI 库脚手架的思路: 包括如何快速并优雅地构建 UI 库的主页, 如何托管主页, 如何编写脚本提升自己的开发效率, 如何生成 CHANGELOG 等等, 这里提供了一个 Demo 可供大家参考:
在线 Demo 地址
GitHub 源码地址
初始化目录结构
主流的开源 UI 库代码结构主要分为三大部分:
组件库本身的代码: 这部分代码会发布到 NPM 上
预览示例和查看文档的网站代码: 类似 Vant https://youzan.github.io/vant/#/zh-CN/intro ,ElementUI 这类网站.
配置文件和脚本文件: 用于打包和发布等等
我们先用 vue-cli3 初始化一个模板, 然后在根目录下新增三个文件夹, 一个用来存放 组件 的代码 (packages), 一个用来存放 预览示例的网站 代码 (examples)(这里直接把初始化模板的 src 目录更改为 examples 即可), 一个用来存放 脚本 代码 (build)
文件的名字可以根据自己喜好去命名.
完成一个组件
具体的代码组织方式可以查看 GitHub 上的源码, 这里需要注意, 我们尽量以组件名来命名文件夹名, 然后在文件夹内新建 index.vue 组件. 这么做是为了方便后面我们用代码直接生成 index.JS 入口文件的内容.
样式文件的分离
为了更好的处理样式, 我们把所有的样式文件单独处理 (代码地址), 这里主要用 Gulp 来处理任务.
发布 NPM 包
打包
当我们完成了一个组件, 就可以打包了, 打包很简单, 这得益于 vue-cli3 的 build 命令引入了构建目标参数, 只需执行
vue-cli-service build --target lib --name vue-cards --dest lib packages/index.JS
就可以把 packages 下所有的代码以库模式打包出去.
在库模式中, Vue 是外置的. 这意味着包中不会有 Vue, 即便你在代码中导入了 Vue. 如果这个库会通过一个打包器使用, 它将尝试通过打包器以依赖的方式加载 Vue; 否则就会回退到一个全局的 Vue 变量.
发布
发布之前, 我们需要新增一个. npmignore 文件, 把一些不需要发布到 NPM 包的文件或者文件夹都写在里面, 写法和. gitignore 一致. 具体怎么发布一个 NPM 包这里就不在赘述了.
文档的编写和发布
编写
可能大多数人觉得写一个开源 UI 库最头疼的事情就是写文档, 如何快速又优雅的构建出像 ElementUI 官网这类网站呢? 目前最流行的写文档的方式就是通过 Markdown 编写, 那我们要解决的就是如何将 Markdown 文档 html 化, 直接展示在页面中. 这里我们可以用 https://github.com/QingWei-Li/vue-markdown-loader 插件, 该插件的具体配置可以查看项目的文件. 具体到本项目的效果如图所示:
代码示例部分都是用 Markdown 编写的, 其他部分则是普通的 vue 组件.
(本项目网站的具体的代码地址)
发布
我们可以利用 GithubPages 功能来发布我们的文档网站, 具体的使用方法网上有很多教程, 比如 GitHub Pages 使用入门 https://zhuanlan.zhihu.com/p/25680246 . 其实还有一种很简单的方式, 可以用 https://github.com/tschaub/gh-pages 这个工具, 一键发布到对应仓库的 gh-pages 分支. 具体配置和使用可以参考本项目的文件.
提高开发效率的一些做法
在本项目的文件夹下, 有很多能够大大提升我们开发效率的文件, 下面来一一讲解一下它们的用途.
get-components.JS 文件主要为了获取 packages 目录下所有的组件目录, 为我们构建 packages 下的入口文件做准备.
build-entry.JS 文件主要是根据 get-components.JS 的结果, 然后将代码写入 / packages/index.JS, 生成入口文件.
build-lib.JS 文件主要是做一些发布 NPM 包前的构建准备, 包括构建入口文件, 构建库, 构建样式文件等.
publish-docs.JS 文件的作用是可以一键发布文档到本仓库的 gh-pages 分支.
release.sh 脚本文件主要是把一些发布 NPM 包的命令集合在了一起, 包括很多 Git 和 NPM 操作.
快速生成 CHANGELOG
CHANGELOG 我们可以自己手写 MD 文档, 当然这并不明智. 我们更希望的是用代码去自动化生成, 原理无非就是提取你的 Git 提交信息并写入文件, 这里我们可以用来生成 CHANGELOG. 为了生成更精细和正确的 CHANGELOG 文档, 我们需要严格规范自己的提交记录, 我们可以用 conventional-changelog 的标准提交记录:, 具体的用法可以参考 https://github.com/commitizen/cz-cli . 本项目的的 init 脚本其实也封装了相关的脚本命令, 可以参考.
参考
详解: Vue cli3 库模式搭建组件库并发布到 NPM
来源: https://juejin.im/post/5c934511f265da60d82dc7ab