mycim-lib-vue3 v0.0.11

title: Mycim Lib Vue3 组件库开发文档

lang: zh-CN

Mycim Lib Vue3 组件库开发文档

快速上手

基于 pnpm 的monorepo(单一代码仓库)工程

构建工具 Vite Rollup

文档 Vitepress

单测工具 Vitest

环境准备

确保 node 已经被成功安装 且版本>=16

node -v
node-version >= 16.0.0

包管理工具

pnpm

npm install -g pnpm

启动项目

使用命令安装该项目所有依赖

pnpm i

组件预览

使用命令

pnpm docs:dev

该项目将启动网站，网站内你可以预览全部现有组件

项目结构

项目大纲

monorepo 工作区配置说明pnpm-workspace.yaml

packages:
  - packages/*  //组件库
  - docs // 文档库
  - play // 测试库
  - internal/* // 脚本库

项目主结构

|—— mycim-lib-vue3
|—— docs /_ 文档站点 _/
|—— internal /_ 内部脚本和配置 _/
|—— packages /_ 核心代码文件 _/
|—— play /_ 组件调试文件 _/
|—— scripts /_ 脚本文件 _/
|—— ssr-testing /_ ssr渲染 _/
|—— typings /_ 全局类型定义 _/
|—— .editorconfig /_ 编辑器格式化配置文件 _/
|—— .env /_ 环境变量配置 _/
|—— .eslintignore /_ 编辑器格式化忽略配置文件 _/
|—— .eslintrc /_ eslint配置 _/
|—— .gitattributes /_ git处理文件时的配置 _/
|—— .gitignore /_ git忽略提交的配置 _/
|—— .gitpod /_  gitPod配置文件 _/
|—— .markdownlint /_ Markdown Lint 工具的配置文件 _/
|—— .npmrc /_ npm 包管理器 _/
|—— .nvmrc /_ node版本管理 nvm配置文件 _/
|—— .prettierignore /_ prettier配置忽略 _/
|—— .prettierrc /_ prettier配置文件 _/
|—— codecov.yml /_ codecov配置文件 _/
|—— commitlint.config.js /_ commitlint工具配置文件 _/
|—— commitlint.config.ts /_ commitlint工具配置文件 _/
|—— global.d.ts /_ 全局类型声明文件 _/
|—— LICENSE /_ 开源协议 _/
|—— package.json /_ package.json _/
|—— pnpm-lock.yaml /_ pnpm锁文件 _/
|—— pnpm-workspace.yaml /_ pnpm的Workspace配置文件 _/
|—— README.md /_ README.md _/
|—— tsconfig.base.json /_ ts基础共享配置 _/
|—— tsconfig.json /_ ts配置 _/
|—— tsconfig.node.json /_ node.js编译ts配置  _/
|—— tsconfig.play.json /_ play项目编译ts配置 _/
|—— tsconfig.vite-config.json /_ vite编译ts配置 _/
|—— tsconfig.vitest.json /_ ts编译配置 _/
|—— tsconfig.web.json /_ ts编译配置 _/
|—— vitest.config.ts /_ 测试环境vite全局配置 _/
|—— vitest.setup.ts /_ 测试环境vite运行时的初始化设置 _/

docs 文档库

|—— docs
|   |—— .vitepress /_ vitepress配置 _/
|   |   |—— build /_ 脚本 _/
|   |   |   |—— crowdin-credentials.ts /_ 获取多语言凭证脚本 _/
|   |   |   |—— crowdin-generate.ts /_ 根据配置合并语言包脚本 _/
|   |   |   |—— rebuild-pwa.ts /_ pwa构建脚本 _/
|   |   |—— config
|   |   |   |—— features.ts /_ vite额外配置 _/
|   |   |   |—— heade.ts /_  项目的生成的HTML页面头部信息添加脚本 _/
|   |   |   |—— index.ts
|   |   |   |—— nav.ts /_ 导航生成脚本 _/
|   |   |   |—— plugings.ts /_ markdown解析脚本 _/
|   |   |   |—— sidebar.ts /_ 侧边栏导航生成脚本 _/
|   |   |—— crowdin /_ 多语言配置 _/
|   |   |   |—— en-US /_ 英文配置(已废弃) _/
|   |   |   |   |—— component /_ vitepress站点组件多语言配置 _/
|   |   |   |   |—— pages /_ vitepress页面多语言配置 _/
|   |   |   |—— zh-CN /_ 中文配置 _/
|   |   |   |   |—— component /_ vitepress站点组件多语言配置 _/
|   |   |   |   |—— pages /_ vitepress页面多语言配置 _/
|   |   |—— i18n /_ 合并之后的多语言文件 _/
|   |   |—— plugins /_ 插件包 _/
|   |   |—— theme /_ 文档站点入口文件 _/
|   |   |—— utils /_ 工具包 _/
|   |   |—— vitepress /_ vitepress文档站点页面和组件 _/
|   |   |   |—— components /_ 站点页面和组件 _/
|   |   |   |—— composables /_ Vue Composables  _/
|   |   |   |—— styles /_ 样式 _/
|   |   |   |—— utils /_ 插件 _/
|   |   |   |—— constant.ts /_ 常量定义 _/
|   |   |   |—— index.ts /_ 中文配置 _/
|   |   |   |—— types.ts /_ 类型定义 _/
|   |   |—— config.mts /_ vitepress配置文件 _/
|   |   |—— dark-mode.js /_ 主题模式切换 _/
|   |   |—— env.d.ts /_ 类型定义 _/
|   |   |—— lang.js /_ 语言设置 _/
|   |   |—— sw.ts /_ Service Worker配置文件 _/
|   |—— en-US /_ 英文文档(已废弃) _/
|   |   |—— component /_ 组件文档 _/
|   |   |   |—— button.md /_ button组件示例文档 _/
|   |   |—— guide /_ 导航文档 _/
|   |   |—— index.md /_ 文档首页 _/
|   |—— examples /_ demo演示示例 _/
|   |   |—— button /_ 按钮组件演示示例 _/
|   |   |   |—— basic.vue /_ 示例 _/
|   |   |—— .eslintrc.json /_ eslint配置文件 _/
|   |—— public /_ 公共图片资源等配置 _/
|   |—— zh-CN /_ 中文文档 _/
|   |   |—— component /_ 组件文档 _/
|   |   |   |—— button.md /_ button组件示例文档 _/
|   |   |—— guide /_ 导航文档 _/
|   |   |—— index.md /_ 文档首页 _/
|   |—— .gitignore /_ git忽略文件 _/
|   |—— conponents.d.ts /_ docs组件全局类型定义 _/
|   |—— crowdin.yml /_ 多语言翻译凭证 _/
|   |—— index.md /_ 默认文档 _/
|   |—— package.json
|   |—— tsconfig.json /_ TS编译配置 _/
|   |—— unocss.config.ts /_ Unocss配置文件 _/
|   |—— vite.config.ts /_ vite配置 _/

play 调试包

|—— play
|   |—— src
|   |   |—— .gitignore /_ git忽略配置 _/
|   |   |—— App.vue /_ 入口主页面文件 _/
|   |—— .eslintrc.json /_ eslint配置 _/
|   |—— app.example.vue /_ 测试示例文件 _/
|   |—— env.d.ts /_ 类型定义 _/
|   |—— main.ts /_ 主入口 _/
|   |—— package.json
|   |—— vite.config.ts /_ vite配置 _/
|   |—— vite.init.ts /_ 初始化配置 _/

packages 组件库核心文件

|—— packages
|   |—— components
|   |   |—— button /_ 按钮组件 _/
|   |   |   |—— __tests__ /_ 单元测试 _/
|   |   |   |—— src /_ 组件代码 _/
|   |   |   |—— style /_ 样式入口 _/
|   |   |   |—— index.ts /_ 按钮组件暴露出口 _/
|   |   |—— index.ts /_ 组件库出口 _/
|   |   |—— package.json
|   |—— constants /_ 组件常量定义 _/
|   |—— directives /_ 组件自定义指令 _/
|   |—— hooks /_ vue hooks _/
|   |—— locale /_ 组件语言包配置 _/
|   |—— mycim-lib-vue3 /_ 组件库对外暴露出口 _/
|   |—— test-utils /_ 单测工具包 _/
|   |—— theme-chalk /_ 样式包 _/
|   |—— utils /_ 组件工具包 _/

internal

|—— internal
|   |—— build /_ 构建脚本 _/
|   |—— build-constants /_ 构建常量定义 _/
|   |—— build-utils /_ 构建工具包 _/
|   |—— eslint-config /_ eslint配置包 _/
|   |—— metadata /_ 组件目录生成工具 _/

开发一个新组件

使用命令快速创建一个组件

pnpm gen <componentName>

执行命令之后，会自动在 packages 下的 components 下生成如下文件

|—— components
|   |—— componentName
|   |   |—— __tests__
|   |   |   |—— componentName.test.tsx
|   |   |—— src
|   |   |   |—— componentName.ts
|   |   |   |—— componentName.vue
|   |   |—— index.ts

新增组件样式文件

在 packages/theme-chalk/src 新增一个 scss 文件

componentName.scss

在 packages/theme-chalk/src/index.scss 里面引用新增的的样式文件

@use './componentName.scss'

新增组件说明文档

在 docs 下新增如下 md 文件

docs/zh-CN/component/componentName.md

新增演示示例文件

在 docs/examples 下新增组件的属性使用示例

|—— docs
|   |—— examples
|   |   |—— componentName
|   |   |   |—— basic.vue

可以在 componentName.md 中通过:::demo引入示例文件，用于在文档中展示组件的用法

:::demo
docs/examples/component/basic.vue
:::

配置 md 文档导航

在 docs/.vitepress/crowdin/zh-CN/pages/component.json 中新增配置，其他语言配置同理新增

{
  // 具体属于哪个模块就写在哪个模块下
  "basic": {
    "text": "Basic 基础组件",
    "children": [
      {
        "link": "/button",
        "text": "Button 按钮"
      },
      {
        "link": "/componentName",
        "text": "componentName 组件名称"
      }
    ]
  }
}

新增后执行生成语言包的命令

pnpm docs:gen-locale

"gen-locale": "rimraf .vitepress/i18n && tsx .vitepress/build/crowdin-generate.ts"

该命令会删除 docs/.vitepress/i18n 下的所有文件，然后将 docs/.vitepress/crowdin 下的所有语言包合并成一个文件用做语言包配置，合并操作可参考脚本.vitepress/build/crowdin-generate.ts

向外部暴露组件

packages/components/index.ts

export * from './componentName'

packages/mycim-lib-vue3/component.ts

import { CimComponentName } from '@mycim-lib-vue3/components/componentName'
import type { Plugin } from 'vue'

export default [CimComponentName] as Plugin[]

:::tip

Cim 为组件命名规则，生成组件时会自动添加前缀，在对外暴露组件时，需要和组件内部的 name 保持一致

:::

全局组件类型定义

全局类型支持和为 Volar 插件定义全局组件和属性

typings/components.d.ts

// For this project development
import '@vue/runtime-core'
declare module '@vue/runtime-core' {
  // GlobalComponents for Volar
  export interface GlobalComponents {
    CimComponentName: typeof import('../packages/mycim-lib-vue3')['CimComponentName']
  }
}

export {}

至此，一个新组件的创建流程完整结束，接下来开始测试及发布流程

单元测试

本项目使用vitest进行单元测试

示例

describe('Button.vue', () => {
  it('loading', () => {
    const wrapper = mount(() => <Button loading />)

    expect(wrapper.classes()).toContain('is-loading')
    expect(wrapper.findComponent(Loading).exists()).toBeTruthy()
  })

  it('size', () => {
    const wrapper = mount(() => <Button size="large" />)

    expect(wrapper.classes()).toContain('el-button--large')
  })
})

在项目根目录下执行以下命令，会启动 vitest 根据执行所有的单测文件，并输出测试报告

pnpm test

在项目根目录下执行以下命令，会执行对应模块的单测文件

pnpm test moduleName

组件本地测试

1. 使用命令

pnpm dev

将启动本地开发环境

2. 将你的组件添加到 play/src/App.vue

App.vue

<template>
  <ComponentYouAreDeveloping />
</template>

<script setup lang="ts">
// 要保证当前组件已注册到 @mycim-lib-vue3/components
import { ComponentYouAreDeveloping } from '@mycim-lib-vue3/components'
</script>

根据需要修改 App.vue 文件让开发过程顺利进行

打包及发布

后续更新