Vue3 + Vite 构建组件库的流程
本文教你如何用 Vue + Vite，一步一步构建一个组件库并发布到 npm 的整体流程
1. 通过 vite 命令创建一个基本的项目结构（这里选用 vue + ts 的项目）
-
npm create vite@latest
2. 在项目中创建一个 lib 目录，用于存放组件库所要编写的组件
3. 我们先在 lib 中编写组件库的第一个组件，用于这次组件库的搭建的组件 - 这里只通过创建一个简单的按钮 button 组件来作为测试
-
<!-- lib/components/HButton.vue --> <script setup lang="ts"> import { ref } from 'vue';defineProps<{title: string }>()const count = ref(0) </script><template><button class="h-button" @click="count++">{{ title }} : {{ count }}</button> </template><style scoped> .h-button {background-color: #409eff;color: white;padding: 0 16px;height: 34px;line-height: 34px;border-radius: 4px;border: 0px;cursor: pointer; }.h-button:hover {background-color: #66b1ff; } </style>
4. 我们可以先在 App.vue 中引入该组件，来测试一下该组件
-
<script setup lang="ts"> import HButton from "../lib/components/HButton.vue" </script><template><h1>app</h1><hr><HButton title="小孔" /> </template> -
5. 当组件测试没有问题后，接下来我们需要在 vite.config.ts 配置文件中，配置项目打包为一个 lib 库模式
-
// vite.config.ts : 项目初始配置 import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({plugins: [vue()], }) -
// // vite.config.ts : 配置 build 打包模式为 lib 库模式 → 下面对应的配置也可以直接在 vite 官方文档中找到对应的示例 import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue'import { resolve } from "path"export default defineConfig({plugins: [vue()],build: {lib: {entry: resolve(__dirname, 'lib/main.ts'), // -- 配置打包的库的入口文件name: 'my-lib-test',fileName: 'my-lib-test' // -- 配置打包的文件名},rollupOptions: {// -- 配置你不需要打包进库中的依赖库（因为该组件库是在 vue 项目中的，所以使用的项目需要本身就有 vue 依赖库了，所以我们在这里不需要打包进组件库中） -- 如果你还有其它的依赖也不想打包进依赖库中，同理external: ['vue'],}} }) -
注意: - 我们将上面的配置好后，我们会发现他的有些代码报错了
-
-
这是因为 vite 创建的项目，默认是没有对应 node 的相关类型的，而 path 与 __dirname 是 node 中的东西 -
解决该问题，我们只需要下载对应的 node 类型库就行了 →npm i @types/node -
-
6. 在对应的 lib 库的入口文件 main.ts 中引入我们所写好的 HButton 组件，并导出我们需要导出的组件
-
// lib/main.ts // -- 引入我们写好的组件并在 main.ts 入口文件中将其导出 → 使其在打包中可以将该组件构建进去 export { default as HButtom } from "./components/HButton.vue"
7. 我们可以先通过 npm run build 来打包一下，来看一下效果
-
-
上面打包后的
dist目录中还有两个先问题，一个是 vite 默认会将public中的内容直接复制到对应的打包目录中，一个是没有将对应的类型声明构建进去-
第一个问题: 我们可以通过在 build 中将 copyPublicDir 配置为 false → 表示构建时不对 public 中的内容进行复制-
// vite.config.ts export default defineConfig({build: {copyPublicDir: false,// ...} })
-
-
第二个问题: 我们可以通过在 vite 中配置 vite-plugin-dts 插件，该插件可以使在库模式下，自动根据源文件生成对应的类型声明文件（🔺因为需要处理的东西比较多，在下面进行介绍 ↓）
-
8. 通过 vite-plugin-dts 来生成对应的类型文件
-
安装: -
npm i vite-plugin-dts -D -
配置:
-
// vite.config.ts import dts from 'vite-plugin-dts'export default defineConfig({plugins: [vue(),dts({ // -- 配置 vite-plugin-dts 插件rollupTypes: true, // -- 是否将说有的类型声明，合并到一个文件中tsconfigPath: "./tsconfig.json" // -- 指定对应的 tsconfig 文件，会根据该配置文件中的 include 配置生成对应的类型声明})],// ... }) -
-
-
如上图，我们会发现一个问题，如果我们配置好对应的 dts 插件后，重新构建时，会出现一些错误，且所生成的类型文件也是存在问题 → 🔺这是因为 dts 中的 tsconfigPath 配置的问题 -
因为 tsconfigPath 我们配置的是 tsconfig.json 中的 include 中不是我们想要包含的文件 -
🔺我们可以创建一个专用于打包的 ts 配置文件（tsconfig.build.json），并将 dts 插件中的 tsconfigPath 配置该 ts 配置文件-
// tsconfig.build.json {"extends": "./tsconfig.json", // -- 除了 include 配置外，其它所有配置都继承于原本的 tsconfig.json 配置文件"include": [ // -- 配置所要包含想要包含的目录（如下就表示 lib 目录下的多有内容）"lib",] } -
export default defineConfig({plugins: [vue(),dts({rollupTypes: true, tsconfigPath: "./tsconfig.build.json" // -- 替换成 tsconfig.build.json 配置文件})] })
-
-
此时，我们在通过 npm run build 时，就不会出现对应的报错，且对应打包的库也能生成正常对应的类型声明文件了
9. 上面还可以做一个小优化，可以通过上图看到，组件中的样式它是打包到一个单独的 css 文件中的，并且默认时不会自动在对应打包的 js 中引入该样式
-
也就是说，我们在使用该组件时需要先引入对应的该库中的 css 文件（如在对应项目 main.ts 项目入口中引入） -
我们也可以通过 "vite-plugin-libcss" 插件来帮助我们自动引入对应的样式文件，该插件可以自动的将对应 css 通过 import 导入到对应捆绑的 js 文件中-
安装:npm i vite-plugin-libcss -D -
配置:-
// vite.config.ts : 在 vite 中配置对应插件 import libCss from 'vite-plugin-libcss';export default defineConfig({plugins: [// ..libCss()],// .. })
-
-
此时，我们打包后查看对应的 js 文件，就会发现它会自动的将对应的 css 进行注入，所以我们现在就可以直接在项目中引入对应的 js 文件中的内容来使用即可
-
10. 现在，我们在 App.vue 组件中导入对应打包后的 dist 目录下的文件中的组件，来进行使用与测试
-
<!-- src/App.vue --> <script setup lang="ts"> import { HButtom } from "../dist/my-lib-test" // -- 引入打包后的库的组件 </script><template><h1>app</h1><hr><HButtom title="小孔" /> </template> -
-
使用起来也一切正常后，接下来我们就可以将该库发布到 npm 上了
11. 现在，发布 npm 包还需要再 package.json 中做一些简单配置，具体如下
-
// package.json {"name": "lib-test", // -- 必填: 库名，必须是唯一的，可以先上 npm 搜索，看是否已经存在该库了（如果已经存在，需要更换名称）"version": "0.0.1", // -- 必填: 版本号（如果更新包内容，此项也必须比前面的版本高）"private": false, // -- 此项默认为 true，需要将其配置成 false 或删除该配置项"type": "module", "main": "./dist/my-lib-test。umd.js", // -- 指定包的入口文件（通过 require 引入包时，加载的文件 ）"module": "./dist/my-lib-test.js", // -- 指定包的入口文件（通过 esmodule 引入时，加载的文件）"types": "./dist/my-lib-test.d.ts", // -- 指定 ts 类型声明文件"files": [ // -- 指定发布包时，所包含的文件和目录"dist"],"description": "测试 lib 组件库", // -- 包描述"scripts": {"dev": "vite","build": "vue-tsc -b && vite build","preview": "vite preview"},"peerDependencies": { // -- 我们可以该库需要依赖的，放到 peerDependencies 配置项中（用于提示用户与再npm中会有对应的显示）"vue": "^3.5.12"},"devDependencies": {"@vitejs/plugin-vue": "^5.1.4","typescript": "~5.6.2","vite": "^5.4.10","vite-plugin-libcss": "^1.1.1","vue-tsc": "^2.1.8","@types/node": "^22.9.0","vite-plugin-dts": "^4.3.0"} }
12. 最后，我们只需要再命令行中执行对应的命令进行发布即可 - tip: 需要有对应的 npm 账号 & 在下面命令操作时，有时候经常会因为网络问题登录或发布失败，可以多尝试几遍
-
🔺在执行下面的命令前，先提几个注意的点:-
(1) npm 的源必须为官方源，如果先前切换成淘宝的源或其它的源后，需要先将 npm 切换会原来的官方源-
npm config set registry https://registry.npmjs.org/
-
-
(2) 在登录会发布过程中，因为 npm 源是国外的，所以可能会经常存在登录失败或上传失败的问题，可能是网络的问题，可以多尝试几遍 -
(3) 当包重名时也会上传失败，所以出错时可以留意一下对应的信息（如下错误示例 ↓）
-
-
1.需要在命令行中通过 "npm login" 命令来登录 npm -
2. 登录成功后，在通过 "npm publish" 命令来进行上传即可-
-
此时，该包我们就成功发布到 npm 中了-tip: 需要注意包重名的问题，在上面的注意示例中有图例
-
13. 此时我们就可以通过 npm 来下载并使用我们的组件库了，下面就为一个基本的使用示例（可跳过不看，因为不是重点） - tip: 此测试库我后续会删除,这里只是演示与测试是否能够正常工作
-
安装:npm i lib-test-kxh -
再 App.vue 中引入并使用-
<script setup lang="ts"> import { HButtom } from "lib-test-kxh"</script><template><h1>App</h1><hr><HButtom title="小孔" /> </template> -
-
)
)
