从零搭建Vue3组件库

站长

2023年05月27日 01:13 · 阅读数 78

背景

为了统一公司产品视觉风格，打造一套更符合公司风格、业务的基础组件库。组件库满足以下诉求：

全新组件：提供ant-design-vue中没有的组件
二次封装组件：在ant-design-vue组件库的基础上进行二次封装，对其进行扩展
定制统一视觉风格的主题
组件文档

第一步项目框架搭建

Monorepo

就是指在一个git仓库中，管理多个模块/包（package），这种类型的项目大都在项目根目录下有一个packages文件夹，分多个项目管理。假如 workspace 中有两个包，结构如下：

+ packages
    + foo
    + bar

这种结构很适合组件库项目，同时管理组件包和组件文档。

pnpm

pnpm 内置了对单一存储库（也称为多包存储库、多项目存储库或单体存储库）的支持，可以创建一个 workspace 以将多个项目合并到一个仓库中。简化：pnpm天然支持monorepo

实现Monorepo

初始化仓库

安装pnpm

$ npm install pnpm -g

初始化package.json

$ pnpm init

实现monorepo的关键根目录下新建一个 pnpm-workspace.yaml 文件，该文件定义了 workspace 的根目录，并能够设置包含 / 排除目录。示例：

packages:
  # 包含 packages/ 目录下的所有子包
  - 'packages/*'
  # 包含 components/ 目录下的所有子包
  - 'components/**'
  # 排除在test目录内的包
  - '!**/test/**'

项目中实现：

packages:
  - "packages/*"

在项目根目录下新建packages文件夹，再建两个子文件夹components（用于开发组件库）、site（用于管理组件文档）。使用vite初始化组件库和文档两个包

$ cd ./packages
$ pnpm create vite

新建的文件夹名词为components，选择vue+ts搭建从零搭建Vue3组件库相同操作创建site包。至此，monorepo结构已经搭建好了，接着开始对components子包进行配置，使之能够开发、打包、发布组件。

第二步组件库环境搭建

初始化

技术栈

Vite+TypeScript+Vue3+Ant Design Vue考虑到site（组件文档包）也需要用到这些依赖，安装的时候使用 -w来实现依赖共享

安装Vite和@vitejs/plugin-vue

@vitejs/plugin-vue用来支持.vue文件的转译

$ pnpm install vite @vitejs/plugin-vue -D -w

安装vue3+Ant Design Vue+Less+TypeScript

$ pnpm i vue@next typescript less ant-design-vue @ant-design/icons-vue -D -w

配置tsconfig.json

新建文件，并配置以下内容

{
    "compilerOptions": {
      "baseUrl": ".",
      "jsx": "preserve",
      "strict": false,
      "target": "ESNext",
      "module": "ESNext",
      "skipLibCheck": true,
      "esModuleInterop": true,
      "moduleResolution": "node",
      "lib": ["esnext", "dom"]
    },
    "include": ["packages/components/src", "packages/site/src"],
}

开发、调试

调整`components`结构

packages/components现在是应用的结构目录，删除一些组件开发中不需要的内容，再加一个组件，最后形成以下的结构：

├── README.md
├── package.json
├── src
│   ├── index.ts
│   ├── ui-button
│   │   └── UiButton.vue
│   └── vite-env.d.ts
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts

在packages/components/src用于存放ui组件，示例组件代码如下：

<script setup lang="ts">
  import { Button } from "ant-design-vue";
</script>

<template>
  <Button danger>
    <slot></slot>
  </Button>
</template>

<style lang="less"></style>

import type { App } from "vue";

import UiButton from "./ui-button/UiButton.vue";

export default {
  install(app: App) {
    app.component("UiButton", UiButton);
  },
};
export { UiButton };

修改`package.json`

修改访问入口和包名

{
  "name": "test-ui",
  "version": "1.0.0",
  "description": "",
  "main": "./src/index.ts",
  "scripts": {
    "build": "vite build"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

在文档包中调试组件

在packages/site目录下执行:

$ pnpm install test-ui

此时在packages/site/package.json中会出现test-ui的依赖，将其改为不限制版本号：

{
  "name": "site",
  ...
  "dependencies": {
    "test-ui": "workspace:*",
    ...
  },
  ...
}

在app.vue中引入test-ui导出的ui-button组件

<script setup lang="ts">
  import { UiButton } from "test-ui";
</script>

<template>
  <ui-button>test-ui</ui-button>
</template>

<style scoped></style>

此时本地页面首页会出现一个按钮～从零搭建Vue3组件库检验一下，给ui-button添加一个默认的图标

<script setup lang="ts">
import { Button } from "ant-design-vue";
import { SearchOutlined } from "@ant-design/icons-vue";
import "ant-design-vue/dist/antd.css";
</script>

<template>
  <Button danger>
    <template #icon><SearchOutlined /></template>
    <slot></slot>
  </Button>
</template>

<style lang="less"></style>

页面会实时更新从零搭建Vue3组件库 🌈 到此组件开发、调试环境就搭建好了，在components中开发组件，在site中引用组件辅助调试组件。

打包发布

修改`vite.config.ts`

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import dts from "vite-plugin-dts";
import { resolve } from "path";

// https://vitejs.dev/config/
export default defineConfig({
  build: {
    emptyOutDir: true,
    lib: {
      entry: {
        index: resolve(__dirname, "./src/index.ts"),
      },
      formats: ["es"],
      name: "test-ui",
    },
    minify: false,
    rollupOptions: {
      // 确保外部化处理那些你不想打包进库的依赖
      external: ["vue", "ant-design-vue"],
      output: {
        chunkFileNames: "common/[name].js",
        entryFileNames: (file) => {
          if (file.name == "index") {
            return "index.js";
          } else {
            return "[name]/index.js";
          }
        },
        // 在 UMD 构建模式下为这些外部化的依赖提供一个全局变量
        globals: {
          vue: "Vue",
        },
      },
    },
    assetsDir: "",
  },
  plugins: [vue(), dts()],
  css: {
    preprocessorOptions: {
      less: {
        javascriptEnabled: true,
      },
    },
  },
});

修改`package.json`

{
  "name": "test-ui", // 包名
  "version": "1.1.0", // 包版本
  "description": "",
  "main": "./src/index.ts", // 包入口
  "scripts": {
    "build": "vite build"
  },
  "files": [
    "dist"
  ],
  "keywords": [],
  "author": "",
  "license": "ISC",
  "peerDependencies": { // test-ui依赖的包，但是不会打包都组件包里，需要使用方另外安装
    "ant-design-vue": "^3.2.16",
    "vue": "^3.2.36"
  }
}

类型申明

为了打包出来有类型申明文件，需要在packages/components/src/ui-button下新建type.ts

import { ExtractPropTypes } from "vue";
import UiButton from "./UiButton.vue";

export type UiButtonProps = ExtractPropTypes<typeof UiButton>;

检验

在packages/components下执行pnpm build，可以看到新增了dist目录，其中有css、js、d.ts文件。

├── index.d.ts
├── index.js
├── style.css
└── ui-button
    └── UiButton.vue.d.ts

命令优化

每次打包、启动文档都需要进入对应的目录里执行命令，太麻烦了，在根目录的package.json中改一下配置

{
  ...
  "scripts": {
    "build": "pnpm --filter test-ui build",
    "dev": "pnpm run --filter site dev",
    "docs:build": "pnpm run --filter site build",
    "pub":"pnpm build && pnpm publish --filter test-ui"
  },
  ...
}

修改配置之后，在根目录下执行pnpm build就能打包组件，执行pnpm dev就能启动文档，执行pnpm pub就能打包并发布npm包（npm发包相关内容略）。

第三步主题定制

组件库中的大部分组件都是基于antd的二次封装，要实现主题定制，只需要修改主题配置即可。

主题文件

在packages/components/src下新建style目录，style的目录结构如下（目录结构、文件拷贝ant-design-vue的主题配置）：

├── color
│   ├── bezierEasing.less
│   ├── colorPalette.less
│   ├── colors.less
│   └── tinyColor.less
├── index.less
└── themes
    └── default.less

调整color、themes里文件的色值、边距等，用于示例，把themes/default.less中的@border-radius-base改为8px。index.less里需要先引用antd的默认主题，然后在用自定义的覆盖：

@import "ant-design-vue/es/style/themes/default.less";
@import "ant-design-vue/dist/antd.less";
@import "./themes/default.less";

主题都定制好之后，在组件入口引入：

...
import "./style/index.less";
...

此时启动会报个错从零搭建Vue3组件库原因是文档项目没有配置less预处理器，在packages/site/vite.config.ts加入一下配置

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()],
  /*** 新增内容 开始***/
  css: {
    preprocessorOptions: {
      less: {
        javascriptEnabled: true,
      },
    },
  },
  /*** 新增内容 结束*** /
});

重新启动文档后，可以看到按钮圆角变为8px，主题定制生效。从零搭建Vue3组件库

修改组件`prefix`

此时出现一个问题，有这么一种场景：在一个使用了antd的项目中，又引入了testUi，那么两个组件库的样式会冲突。那么可以通过修改class来做隔离，最终采用设置prefix来实现。

设置`css`的`prefix`

antd提供了配置less文件中prefix的变量：packages/components/src/style/themes/default.less，修改该文件中的@ant-prefix，把ant改为testui。这个时候发现上一步的自定义主题实效了，原因是虽然less文件中的class前缀改成了testui，但是html中的元素绑定的class的前缀还是ant。

修改组件`prefix`

二次封装组件时，使用到antd组件，组件支持传入prefix，以button为例，设置prefix-cls="testui-btn"：

<script setup lang="ts">
import { Button } from "ant-design-vue";
import { SearchOutlined } from "@ant-design/icons-vue";
import "ant-design-vue/dist/antd.css";
</script>

<template>
  <Button danger prefix-cls="testui-btn">
    <template #icon><SearchOutlined /></template>
    <slot></slot>
  </Button>
</template>

<style lang="less"></style>

prefixCls的组合规则：自定义前缀−{自定义前缀}-自定义前缀−{组件名词}组件前缀文档没有列出，只能通过查看antd的源码来确定，查看方法（以button为例）：components/button/button.tsx中，搜索useConfigInject方法，第一个参数就是组件前缀。优化每个组件都写死自定义前缀，万一要修改就会比较麻烦，所以提取一个公共方法

const defaultPrefixCls = "testui";
export function usePrefixCls(suffixCls: string) {
  return `${defaultPrefixCls}-${suffixCls}`;
}

修改组件代码

<script setup lang="ts">
  import { Button } from "ant-design-vue";
  import { SearchOutlined } from "@ant-design/icons-vue";
  /*** 新增下面这行 ***/
  import { usePrefixCls } from "../composables/useUtils";
  import "ant-design-vue/dist/antd.css";
</script>

<template>
	<!--   修改下面这行的prefix-cls -->
  <Button danger :prefix-cls="usePrefixCls('btn')">
    <template #icon><SearchOutlined /></template>
		<slot></slot>
	</Button>
</template>
<style lang="less"></style>

到此，组件主题定制就完成了🎉

第四步组件库文档配置

`vitePress`

基于项目技术栈（vue3+vite）考虑，选用vitepress来搭建文档网站。

VitePress 是 VuePress 小兄弟, 基于 Vite构建。

官方介绍是在vuePress基础上改进了几个点：使用vue3、使用vite、页面更加轻量级等。详情见：vitejs.cn/vitepress/

搭建

在site目录下执行以下命令，安装vitepress、新建docs目录和一个markdown文件。

$ pnpm install vitepress -D
$ mkdir docs && echo '# Hello VitePress' > docs/index.md

在package.json文件中添加启动命令

{
  "name": "site",
  "version": "1.0.0",
  "main": "index.js",
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": "",
  "type": "module",
  "scripts": {
    "start": "vitepress dev docs --host",
    "dev": "npm run start",
    "build": "vitepress build docs",
    "serve": "vitepress serve docs"
  },
  "dependencies": {
    "test-ui": "workspace:*",
  },
  "devDependencies": {
    "vitepress": "1.0.0-alpha.63"
  }
}

启动文档

$ pnpm start

从零搭建Vue3组件库结构搭建

.
└── .vitepress
		├── config.ts # 网站配置文件
    └── theme
        ├── index.css # 网站定制样式
        └── index.ts # 自定义样式导出
├── changelog
├── components # 存放以组件为维度的markdown文件
├── demo # 存放组件demo
├── guide #放概览、引导页
│   ├── getting-started.md
│   └── index.md
├── index.md # 首页
└── public # 放静态文件

配置

首页

参考vitepress官方的配置，在此copy到packages/site/docs/index.md上，然后改巴改巴。设置logo、顶部菜单，把logo和favico放在packages/site/docs/public下

import { version } from "../../package.json";
import { defineConfig } from "vitepress";

export default defineConfig({
  appearance: false, // 夜间模式切换
  title: "TEST UI",
  description: "Vue基础组件库",
  lang: "zh-CN",
  lastUpdated: true,
  head: [["link", { rel: "icon", href: "/favico.png" }]],
  themeConfig: {
    siteTitle: "TEST UI",
    logo: "/logo.png",
    nav: [
      { text: "首页", link: "/" }
    ],
  },
});

设置全局主题色

:root {
    --vp-c-brand: #1890ff;
    --vp-button-brand-border: #1890ff;
    --vp-button-brand-hover-border: #40a9ff;
    --vp-button-brand-hover-bg: #40a9ff;
}

在theme/index.ts中引入index.css

import type { Theme } from "vitepress";
import DefaultTheme from "vitepress/theme";
import "./index.css";

export default DefaultTheme

然后就变成下面的样子从零搭建Vue3组件库首页差不多配置好了，接着就是补充指南、组件页面

指南

在首页把入口配置上

...
export default defineConfig({
  ...
  themeConfig: {
    ...
    nav: [
      { text: "首页", link: "/" },
+      { text: "指南", link: "/guide/getting-started" },
+      { text: "组件", link: "/components/Button.html" },
+      {
+        text: version,
+        items: [
+          {
+            text: "变更日志",
+            link: "/changelog/CHANGELOG.md",
+          },
+        ],
+      },
    ],
  },
});

此时首页右上角就出现了三个入口从零搭建Vue3组件库但是现在点按钮会跳转去404页面，需要新建页面packages/site/docs/guide/getting-started.md（内容略，直接拷贝element-ui官网-快速上手用作示例）。

组件页

组件页和指南有点差别，需要在页面左侧加侧边导航，增加如下配置：

...
export default defineConfig({
  ...
  themeConfig: {
    ...
    nav: [
      ...
    ],
+    sidebar: {
+      "/components/": [
+        {
+          text: "基础组件",
+          items: [{ text: "Button 按钮", link: "/components/Button" }],
+        },
+      ],
+    },
  },
});

新建/components/Button.md，简单加点内容

# 按钮

按钮用于开始一个即时操作。

# 使用说明

一个操作区域尽量保证只有一个主按钮。
按钮的主次顺序为：主按钮>次按钮>文字按钮。

# 展示

### 按钮类型

主按钮、次按钮、普通按钮、图标按钮，不同的类型可以用来区别按钮的重要程度。

### 属性

继承于[Antd-vue Button 组件 API](https://www.antdv.com/components/button-cn#API)

为了让markdown支持展示demo，引入vite-plugin-vitepress-demo(项目中版本号用的是2.0.0-alpha.8)

$ pnpm install -D vite-plugin-vitepress-demo

在config.ts中加入一些配置

...
+import { vitePluginVitepressDemo } from "vite-plugin-vitepress-demo";

export default defineConfig({
+  vite: {
+    plugins: [
+      vitePluginVitepressDemo({
+        glob: ["**/demo/**/*.vue"], // 指定需要处理的文件
+      }),
+    ],
+  	css: {
+      preprocessorOptions: {
+        less: {
+          javascriptEnabled: true,
+        },
+      },
+    },
+  },
  appearance: false, // 夜间模式切换
  ...
});

使用这个插件提供的默认主题，此外demo中会用到ant-design-vue（在项目根目录已经安装好依赖，无需再装），也把它引进来

import type { Theme } from "vitepress";
import DefaultTheme from "vitepress/theme";
import { AntdTheme } from "vite-plugin-vitepress-demo/theme";
import Antd from "ant-design-vue";
import "test-ui/dist/style.css";
import "ant-design-vue/dist/antd.css";
import "./index.css";

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component("Demo", AntdTheme).use(Antd);
  },
} as Theme;

建一个目录专门放demo，再创建个button的demo.vue，其中使用组件库开发好的ui-button

<script setup lang="ts">
  import { UiButton } from "test-ui";
</script>

<template>
  <ui-button>主按钮</ui-button>
</template>

<style lang="less" scoped></style>

在markdown中引入这个demo

# 按钮

按钮用于开始一个即时操作。

# 使用说明

一个操作区域尽量保证只有一个主按钮。
按钮的主次顺序为：主按钮>次按钮>文字按钮。

# 展示

### 按钮类型

主按钮、次按钮、普通按钮、图标按钮，不同的类型可以用来区别按钮的重要程度。

<demo src="../demo/button/demo.vue" title="标题" desc="描述"></demo>

### 属性

继承于[Antd-vue Button 组件 API](https://www.antdv.com/components/button-cn#API)

启动项目，页面上就能展示button的demo了从零搭建Vue3组件库到此，文档网站结构、配置都已经开发好了🎉

第五步项目代码规范

目标有三个：

在开发的时候，vscode有eslint提示
文件保存能自动格式化
在提交代码的时候，不符合代码规范的，提交失败

打算另开一章写（写不动了）。

第六步版本管理

项目中使用的是changeset做版本管理，先略了吧。

补充

转载自:https://juejin.cn/post/7237032198279446585

从零搭建Vue3组件库

背景

第一步 项目框架搭建

Monorepo

pnpm

实现Monorepo

初始化仓库

第二步 组件库环境搭建

初始化

技术栈

安装Vite和@vitejs/plugin-vue

安装vue3+Ant Design Vue+Less+TypeScript

配置tsconfig.json

开发、调试

调整components结构

修改package.json

在文档包中调试组件

打包发布

修改vite.config.ts

修改package.json

类型申明

检验

命令优化

第三步 主题定制

主题文件

修改组件prefix

设置css的prefix

修改组件prefix

第四步 组件库文档配置

vitePress

搭建

配置

首页

指南

组件页

第五步 项目代码规范

第六步 版本管理

补充

第一步项目框架搭建

第二步组件库环境搭建

调整`components`结构

修改`package.json`

修改`vite.config.ts`

修改`package.json`

第三步主题定制

修改组件`prefix`

设置`css`的`prefix`

修改组件`prefix`

第四步组件库文档配置

`vitePress`

第五步项目代码规范

第六步版本管理