1、工程搭建 -- 渐进式vue3的组件库通关秘籍

1、前言

本系列文章准备通过渐进式的开发，来构建一个基于vue3的组件库，主要目的是用来学习vue3和前端组件的相关知识。主要参考和模仿and-design-vue，输出自己对组件库构建学习过程中的理解。

所用的技术栈为：vue3 + ts + jsx + webpack + vitepress(文档)

本节需要你了解vue3的使用，jsx的相关知识 。

2、本节目的

• 完成一个node工程的搭建
• 完成第一个hello-world组件
• 基于vitepress构建组件库的文档网站，同时支持组件预览。
• 完成第一个组件 hello world的开发和文档输出
• 提交代码到git，配置git pages

3、组件库构建初始化

3.1 准备工作

前提：

• node版本为 20+，推荐使用 nvm 管理node版本

  ☘️ window安装看这里

  ☘️ Mac安装看这里

  mac也可以直接使用brew安装

  brew install nvm
  

• 本工程使用npm来管理依赖

  npm install cnpm -g --registry=https://registry.npmmirror.com
  

3.2 初始化工程

为你的工程准备一个文件夹，这里我命名为fake-ui

进入到文件夹内，执行以下命令：

npm init

除了版本号，其余内容可以按照自己喜好填写，版本号按照规范使用 1.0.0 作为初始版本号

可以使用vscode打开我们的工程看一下，目前里面就一个package.json

接下来我们在根目录下新建一个空的入口文件 index.js 作为工程的入口文件，

注意：这里的入口文件和 package.json 里面的 **main **对应的 index.js 不是一个含义，这一点后面会详细说明。

3.3 第一个组件

首先，在根目录下新建一个文件夹 components,后续所有的组件都将存放在这里。

然后，在 components 文件夹下新建第一个组件 hello world，文件夹结构如下

• hello-world.tsx 组件的源码
• hello-world/index.ts 用以导出组件相关的内容
• components/components.ts 导入并导出所有的组件
• components/index.ts 用以统一导出所有的组件

下面在hello-world.tsx组件内新增以下内容：

// components/hello-world/hello-world.tsx
import { defineComponent } from "vue";

export default defineComponent({
  setup() {
    const render = () => {
      return (
        <>
          <div>hello world</div>
        </>
      );
    };
    return render;
  },
});

测试文件内部可能会有报错，我们先不用理会，等后面安装完依赖和配置就好了。

然后在 hello-world/index.ts 和 components/components.ts, components/index.ts 内将我们的组件导出即可。

// hello-world/index.ts
import helloWorld from "./hello-world";

export default helloWorld;

// components/components.ts
export { default as HelloWorld } from './hellow-world';

这里的 export { default as * } 就是将组件的默认导出转换为命名导出。

// components/index.ts
export * from './components';

此文件只需修改一次，后续只用在 components/components.ts 内导出新增的组件即可。

至此，我们的第一个组件的编写和导出工作已经完成，但是现在还没有办法预览。接下来我们将使用 vitepress 搭建一个文档网站，实现组件文档的编写和预览。

3.4 基于vitepress构建文档网站

VitePress 是一个静态站点生成器 (SSG)，专为构建快速、以内容为中心的站点而设计。简而言之，VitePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。同时支持vue和react的组件。

我们在当前项目根目录下打开shell, 安装vitepress

npm add -D vitepress

VitePress 附带一个命令行设置向导，可以帮助我们构建一个基本项目。安装后，通过运行以下命令启动向导：

npx vitepress init

配置选择默认配置即可。

完成之后我们的根目录会生成一个docs文件夹，里面就是我们文档网站的所有内容，关于更多的vitepress的使用教程可以看：vitepress文档。

docs:dev 脚本将启动具有即时热更新的本地开发服务器。可以实时预览文档和组件的修改。

npm run docs:dev

然后在浏览器里面 http://localhost:5173/，看到下面的页面就说明我们的文档网站启动成功了。

接下来我们修改文档的内容，使之适配我们的组件库内容。

修改 docs/index.md 内容，这是文档网站的入口，即主页。内容如下：

---
# https://vitepress.dev/reference/default-theme-home-page
layout: home

hero:
  name: "fake-ui"
  text: "渐进式的学习如何构建vue3组件库"
  tagline: 千里之行，始于足下
  actions:
    - theme: brand
      text: 组件库
      link: /components/index

features:
  - title: 渐进式学习
    details: 从下而上的逐步构建一个组件库。
  - title: 啰嗦且详细
    details: 涉及到的知识点都会不厌其烦的写下来。
  - title: 学习用的，欢迎共建
    details: 我也是第一次，有意见和兴趣的欢迎来搞事。
---

删除 docs/api-examples.md, docs/markdown-examples.md

新增 docs/components/hello-world.md，支持vue组件。内容如下：

---
outline: deep
---

# hello world

say hello to the world!

## 代码演示

<script setup>
import { HelloWorld } from '../../components' 
</script>

<HelloWorld />
```vue
<script setup>
import { HelloWorld } from '../../components' 
</script>

<HelloWorld />
```

新增 docs/components/index.md 作为组件文档的主页。

## fake ui 组件库文档

修改 docs/.vitepress/config.mts ，修改文档导航。

import { defineConfig } from "vitepress";

// https://vitepress.dev/reference/site-config
export default defineConfig({
  title: "fake-ui",
  description: "fake-ui vue3 progressive ui component study",
  themeConfig: {
    // https://vitepress.dev/reference/default-theme-config
    nav: [
      { text: "主页", link: "/" },
      { text: "组件", link: "/components/index" },
    ],

    sidebar: [
      {
        text: "组件",
        items: [{ text: "Hello World", link: "/components/hello-world" }],
      },
    ],
  },
});

保存预览。

点击：组件==> hello-world 会出现报错，因为vitepress默认不支持jsx, 我们可以通过vite.config.ts增加一个支持jsx的plugin即可。

新增 docs/vite.config.js，内容如下：

import { defineConfig } from "vite";
import vueJsx from "@vitejs/plugin-vue-jsx";
export default defineConfig({
  plugins: [vueJsx()],
});

安装依赖: vue3、@vitejs/plugin-vue-jsx ：

npm i vue
npm i @vitejs/plugin-vue-jsx --save-dev

然后重新运行，即可看到组件的文档和预览了。

npm run docs:dev

你可以随意修改hello-world.md的内容，然后报错看看文档的变化。

OK，至此我们完成了文档网站的构建和组件的预览。后续只需要在components文件夹下增加对应组件的md文档即可。

4、发布到github

由于vitepress站点需要编译之后才能部署使用，所以，我们这里借助github actions帮助我们在提交代码后，自动构建并同步git pages。

新建 .github/workflows/doc-build.yml

# Sample workflow for building and deploying a VitePress site to GitHub Pages
#
name: 打包部署vitepress到github pages

on:
  # Runs on pushes targeting the `main` branch. Change this to `master` if you're
  # using the `master` branch as the default branch.
  push:
    branches: [dev]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # Build job
  build:
    name: "打包"
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0 # Not needed if lastUpdated is not enabled
      # - uses: pnpm/action-setup@v2 # Uncomment this if you're using pnpm
      # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
      - name: 设置node
        uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: npm # or pnpm / yarn
      - name: 打包流程
        uses: actions/configure-pages@v3
      - name: 安装依赖
        run: npm i
      - name: 打包
        run: |
          npm run docs:build
          touch docs/.vitepress/dist/.nojekyll
      - name: 上传制品
        uses: actions/upload-pages-artifact@v2
        with:
          path: docs/.vitepress/dist

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: 部署
    steps:
      - name: 部署到 GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

修改 docs/.vitepress/config.mts，为打包后的静态文件增加 publicPath

import { defineConfig } from "vitepress";

// https://vitepress.dev/reference/site-config
export default defineConfig({
  base: "/fake-ui/", // 新增
  ...
});

在github仓库中配置pages

在环境里面配置支持部署的分支，点击进去，修改你想要的分支即可，这里我们修改为dev分支，对应doc-build.yml 里面的配置。

最后将所有代码提交到对应的分支即可, 我们这里是

• 提交到 feature_1.0_init_project 分支
• merge 到 dev 分支

本节代码分支：feature_1.0_init_project

5、下一节

组件库打包构建，按需加载，webpack、babel配置详解。

欢迎点赞、欢迎star、欢迎讨论、一起学习。