## File: README.md

---

### Intro

Varlet is a `Vue3` component library based on Material Design 2 and 3, supporting mobile and desktop, developed and maintained by `varletjs` organization.


### Features

- 🚀   Provide 70+ high quality general purpose components
- 🚀   Components are very lightweight
- 💪   Developed by Chinese, complete Chinese and English documentation and logistics support
- 🛠️   Support on-demand introduction
- 🛠️   Support theme customization
- 🌍   Support internationalization
- 💡   Support WebStorm syntax highlighting
- 💪   Support the SSR
- 📦   Support [Nuxt Module](https://github.com/varletjs/varlet-nuxt)
- 💡   Support the Typescript
- 💪   Make sure more than 90 percent unit test coverage, providing stability assurance
- 🎨   Supports both Material Design 2 and Material Design 3 design systems
- 🛠️   Support dark mode
- 🔧   Provide official VSCode extension
- ⌨️   Support Accessibility (still improving)

### Install

### CDN
`varlet.js` contain all the styles and logic of the component library, and you can import them.

```html

<script src="https://cdn.jsdelivr.net/npm/vue"></script>
 
<script src="https://cdn.jsdelivr.net/npm/@varlet/touch-emulator/iife.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@varlet/ui/umd/varlet.js"></script>
<script>
  const app = Vue.createApp({
    template: '<var-button>Button</var-button>'
  })
  app.use(Varlet).mount('#app')
</script>
```

### Webpack / Vite
```shell
# Install with npm or yarn or pnpm

# npm
npm i @varlet/ui -S

# yarn
yarn add @varlet/ui

# pnpm
pnpm add @varlet/ui
```

```js
import App from './App.vue'
import Varlet from '@varlet/ui'
import { createApp } from 'vue'
import '@varlet/ui/es/style'

createApp(App).use(Varlet).mount('#app')
```

### Official Ecosystem

The following projects are maintained by the official team for a long time.

| Name | Description |
|------------------------------------------------------------------------------------------------------|--------------------------------------|
| [@varlet/cli](https://github.com/varletjs/varlet/tree/dev/packages/varlet-cli) | `Vue3 component library rapid prototyping tool` |
| [@varlet/touch-emulator](https://github.com/varletjs/varlet/tree/dev/packages/varlet-touch-emulator) | `Desktop adapter, so that the mobile component library can run on the desktop` |
| [@varlet/ui-playground](https://github.com/varletjs/varlet/tree/dev/packages/varlet-ui-playground) | `Varlet component library online editing tool` |
| [@varlet/import-resolver](https://github.com/varletjs/varlet/tree/dev/packages/varlet-import-resolver)  | `A resolver for` [unplugin-vue-components](https://github.com/unplugin/unplugin-vue-components) ` used to implement Varlet and import it on demand`   |
| [@varlet/preset-unocss](https://github.com/varletjs/varlet/tree/dev/packages/varlet-preset-unocss)  | [UnoCss](https://unocss.dev/) `presets for varlet` |
| [@varlet/preset-tailwindcss](https://github.com/varletjs/varlet/tree/dev/packages/varlet-preset-tailwindcss)  | [tailwindcss](https://tailwindcss.com/) `presets for varlet` |
| [varlet-theme-builder](https://github.com/varletjs/varlet-theme-builder) | `Theme generator for generating theme variables for varlet Material Design 3` | 
| [varlet-vscode-extension](https://github.com/varletjs/varlet/tree/dev/packages/varlet-vscode-extension) | `Varlet Component Library VSCode Plugin` |
| [vscode-theme-varlet](https://github.com/varletjs/vscode-theme-varlet)  | `Varlet VSCode Theme`   |
| [varlet-app-example](https://github.com/varletjs/varlet-app-template)  | `Varlet component library app template`   |
| [varlet-install-example](https://github.com/varletjs/varlet-install-example)  | `Case collection of Varlet component library and various ecosystem integration` |

### Community Ecosystem

The following projects are maintained by community personnel, welcome to add.

| Name | Description |
|----------------------------------------------------------------|-----------------------------------------|
| [vue-h5-template](https://github.com/sunniejs/vue-h5-template) | `Vue-based mobile template scaffolding, providing mobile presets for Varlet component library` |
| [create-vite-app](https://github.com/ErKeLost/create-vite-app) | `A desktop template scaffolding based on Vue3, providing desktop presets for Varlet component library` |
| [vscode-common-intellisense](https://github.com/Simon-He95/vscode-common-intellisense) | `A VS Code extension that provides better intellisense to Varlet developers` |
| [vue3-varlet-mobile](https://github.com/vue-zone/vue3-varlet-mobile) | `A mobile template based on Vue 3 and Varlet Component Library` |

### Playground

See [Varlet UI Playground](https://varletjs.org/playground).

### Contribution

See [Contributing Guide](https://github.com/varletjs/varlet/blob/dev/.github/CONTRIBUTING.md).

### GitCode Repo

See [Here](https://gitcode.com/varletjs/varlet).

### Thanks to contributors

<a href="https://github.com/varletjs/varlet/graphs/contributors">
  
</a>

### Thanks to the following sponsors

<a href="https://cdn.jsdelivr.net/gh/varletjs/varlet-static/sponsorkit/sponsors.svg">
  
</a>

### Sponsor this project

Sponsor this project to support our better creation. 

#### Wechat / Alipay

---

## File: packages/varlet-vscode-extension/README.md

# Varlet VSCode Extension
English | [中文](README.zh-CN.md)
### Intro

For a better development experience, we built a `VSCode plugin`.

### Features

- 🛠️ &nbsp;Support syntax hints and quick completion for all components.
- 🛠️ &nbsp;Support document address preview and quick jump for all components.
- 🛠️ &nbsp;Support frame selection of code snippets to quickly open `Playground`.
- 🛠️ &nbsp;Support full icon preview for icon components.
- 🌍 &nbsp;Support switching between Chinese and English.

### Install

VsCode Extension Marketplace Search [varlet-vscode-extension](https://marketplace.visualstudio.com/items?itemName=haoziqaq.varlet-vscode-extension).

### How To Use

Grammatical hints appear when you enter the keyword of the component name, and you can quickly complete it after selecting it.



Moving the mouse to the component name will display the document address of the component, which can be clicked to jump.



Press space or attribute keywords in the attribute input range of the label to display attribute completion prompts and attribute information.



When the `name` property of the `Icon` component is input, an icon preview will appear, and syntax completion will be performed after selection.



Frame the code snippet, and you can quickly open `Playground` in the right-click menu to preview the framed code online.



Support switching between Chinese and English, more friendly to Chinese people.

---

## File: packages/varlet-vscode-extension/README.zh-CN.md

# Varlet VSCode Extension
[English](README.md) | 中文
### 介绍

为了更优秀的开发体验，我们构建了一个 `VSCode 插件`。

### 特性

- 🛠️ &nbsp;支持全组件的语法提示、快速补全。
- 🛠️ &nbsp;支持全组件的文档地址预览、快速跳转。
- 🛠️ &nbsp;支持框选代码片段，快速打开 `Playground`。
- 🛠️ &nbsp;支持图标组件的全图标预览。
- 🌍 &nbsp;支持中英文切换。

### 安装

VsCode 插件市场搜索 [varlet-vscode-extension](https://marketplace.visualstudio.com/items?itemName=haoziqaq.varlet-vscode-extension)。

### 如何使用

输入组件名称关键字时出现语法提示，选中后进行快速补全。



鼠标移动到组件名会显示组件的文档地址，可以点击进行跳转。



在标签的属性输入范围按下空格或属性关键字，显示属性补全提示和属性信息。



输入 `Icon` 组件的 `name` 属性时出现图标预览，选中后进行语法补全。



框选代码片段，右键菜单中可以快速打开 `Playground` 对框选的代码进行线上预览。



支持中英文切换，对中国人更加友好。

---

## File: packages/varlet-ui-playground/src/download/template/README.md

# Varlet Playground Demo

To start:

```sh
npm install
npm run dev

# if using yarn:
yarn
yarn dev
```

---

## File: packages/varlet-ui/docs/atomicCssSupport.en-US.md

# Atomic CSS support

### Intro

We've provided common CSS atomization framework presets, made it easier to access the component library's underlying style variables, and standardized page responsiveness breakpoints.

### UnoCSS

#### Install

```shell
# playground-ignore
# npm
npm i @varlet/preset-unocss -D
# yarn
yarn add @varlet/preset-unocss -D
# pnpm
pnpm add @varlet/preset-unocss -D
```

#### Configuration

```js
// playground-ignore
// uno.config.ts
import { defineConfig, presetUno } from 'unocss'
import { presetVarlet } from '@varlet/preset-unocss'

export default defineConfig({
  presets: [presetUno(), presetVarlet()]
})
```

#### More Options

Presets detailed definition [please watch here](https://github.com/varletjs/varlet/blob/main/packages/varlet-preset-unocss/src/index.ts).

### Tailwindcss

#### Install

```shell
# playground-ignore
# npm
npm i @varlet/preset-tailwindcss -D
# yarn
yarn add @varlet/preset-tailwindcss -D
# pnpm
pnpm add @varlet/preset-tailwindcss -D
```

#### Tailwindcss V3 Configuration

```js
// playground-ignore
// tailwind.config.js
import { presetVarlet } from '@varlet/preset-tailwindcss'

export default {
  content: [
    './index.html',
    './src/**/*.{vue,js,ts,jsx,tsx}',
  ],
  presets: [presetVarlet()]
}
```

#### Tailwindcss V4 Configuration

```js
// playground-ignore
// tailwind.config.js
import { presetVarlet } from '@varlet/preset-tailwindcss'

export default {
  presets: [presetVarlet()]
}
```

```css
/** src/style.css */
@import "tailwindcss";
@config "../tailwind.config.js";
```

### More Options

Presets detailed definition [please watch here](https://github.com/varletjs/varlet/blob/main/packages/varlet-preset-tailwindcss/src/index.ts).

### Usage

```html

<template>
  hello
  world
  varlet
</template>
```

We also support the HSL variables, which makes the transparency of adjusting the color easier.

```html

<template>
  hello
</template>
```

---

## File: packages/varlet-ui/docs/atomicCssSupport.zh-CN.md

# 原子化 CSS 支持

### 介绍

我们提供了常见的 CSS 原子化框架预设，使访问组件库的基础样式变量更加容易，并且一致化了页面响应式断点。

### UnoCSS

#### 安装

```shell
# playground-ignore
# npm
npm i @varlet/preset-unocss -D
# yarn
yarn add @varlet/preset-unocss -D
# pnpm
pnpm add @varlet/preset-unocss -D
```

#### 配置

```js
// playground-ignore
// uno.config.ts
import { defineConfig, presetUno } from 'unocss'
import { presetVarlet } from '@varlet/preset-unocss'

export default defineConfig({
  presets: [presetUno(), presetVarlet()]
})
```

#### 更多配置

预设的详细定义[请看这里](https://github.com/varletjs/varlet/blob/main/packages/varlet-preset-unocss/src/index.ts)。

### Tailwindcss

#### 安装

```shell
# playground-ignore
# npm
npm i @varlet/preset-tailwindcss -D
# yarn
yarn add @varlet/preset-tailwindcss -D
# pnpm
pnpm add @varlet/preset-tailwindcss -D
```

#### Tailwindcss V3 配置

```js
// playground-ignore
// tailwind.config.js
import { presetVarlet } from '@varlet/preset-tailwindcss'

export default {
  content: [
    './index.html',
    './src/**/*.{vue,js,ts,jsx,tsx}',
  ],
  presets: [presetVarlet()]
}
```

#### Tailwindcss V4 配置

```js
// playground-ignore
// tailwind.config.js
import { presetVarlet } from '@varlet/preset-tailwindcss'

export default {
  presets: [presetVarlet()]
}
```

```css
/** src/style.css */
@import "tailwindcss";
@config "../tailwind.config.js";
```

#### 更多配置

预设的详细定义[请看这里](https://github.com/varletjs/varlet/blob/main/packages/varlet-preset-tailwindcss/src/index.ts)。

### 使用方式

```html

<template>
  hello
  world
  varlet
</template>
```

我们同时也支持了 hsl 变量，这使得调整颜色的透明度变得更加容易。

```html

<template>
  hello
</template>
```

---

## File: packages/varlet-ui/docs/browserAdaptation.en-US.md

# Browser Adaptation

### Intro

The component library provides mobile and desktop adaptations,
scheme `varlet-touch-emulator` is used for mobile terminal adaptation,
scheme `varlet-touch-emulator` is used for mobile terminal adaptation.

### Mobile Adaptation

#### CSS Unit Adaptation

The component library design is based on the `375px` width design draft. 
It is recommended to use [postcss-px-to-viewport](https://github.com/evrone/postcss-px-to-viewport) to convert `px` units into `vw` units to achieve mobile terminal adaptation.
Create `postcss.config.js` under the `Webpack/Vite` project root path And do the following configuration `375px -> 100vw`.

```shell
# playground-ignore
# npm
npm i postcss-px-to-viewport -D

# yarn
yarn add postcss-px-to-viewport -D

# pnpm
pnpm add postcss-px-to-viewport -D
```

```js
// playground-ignore
// postcss.config.js
module.exports = {
  plugins: {
    'postcss-px-to-viewport': {
      viewportWidth: 375,
      unitPrecision: 6,
      unitToConvert: 'px',
      viewportUnit: 'vmin',
      fontViewportUnit: 'vmin',
      propList: ['*'],
    }
  }
}
```

#### Theme Unit Adaptation (Viewport)

Because the theme is mounted at runtime and is not affected by postcss, the component library provides a utility tool `Themes.toViewport` for adaptation. The theme returned by the function will use the `375px -> 100vmin` rule by default.

```js
import { Themes } from '@varlet/ui'

const viewportTheme = Themes.toViewport(Themes.md3Dark)
```

You can also make changes to the conversion rules

```js
import { Themes } from '@varlet/ui'

const viewportTheme = Themes.toViewport(Themes.md3Dark, {
  // defaults 375
  viewportWidth: 750,
  // defaults 'vmin'
  viewportUnit: 'vw',
  // defaults 6
  unitPrecision: 4,
})
```

#### Theme Unit Adaptation (Rem)

Similar to the Viewport solution

```js
import { Themes } from '@varlet/ui'

const remTheme = Themes.toRem(Themes.md3Dark)
```

Or customize

```js
import { Themes } from '@varlet/ui'

const viewportTheme = Themes.toRem(Themes.md3Dark, {
  // defaults 16
  rootFontSize: 32,
  // defaults 6
  unitPrecision: 4,
})
```

### Desktop Adaptation

Because component library interaction events are developed using `touch` events, `mouse` events on the desktop side are not supported.
It is recommended to use `@varlet/touch-emulator` to set `touch -> mouse` for desktop adaptation.

```shell
# playground-ignore
# npm
npm i @varlet/touch-emulator
# yarn
yarn add @varlet/touch-emulator
# pnpm
pnpm add @varlet/touch-emulator
```

```js
// playground-ignore
import '@varlet/touch-emulator'
```

---

## File: packages/varlet-ui/docs/browserAdaptation.zh-CN.md

# 浏览器适配

### 介绍

组件库提供移动端和桌面端适配方案，
移动端使用 [postcss-px-to-viewport](https://github.com/evrone/postcss-px-to-viewport) 方案进行适配，
桌面端使用 `@varlet/touch-emulator` 方案进行适配。

### 移动端适配

#### CSS 单位适配

组件库设计基于 `375px` 宽度设计稿，推荐使用 postcss 插件将 `px` 单位转换成 `vmin` 单位从而实现移动端适配。
在 `webpack/vite` 项目根路径下创建 `postcss.config.js` 并做如下配置之后 `375px -> 100vmin`。

```shell
# playground-ignore
# npm
npm i postcss-px-to-viewport -D

# yarn
yarn add postcss-px-to-viewport -D

# pnpm
pnpm add postcss-px-to-viewport -D
```

```js
// playground-ignore
// postcss.config.js
module.exports = {
  plugins: {
    'postcss-px-to-viewport': {
      viewportWidth: 375,
      unitPrecision: 6,
      unitToConvert: 'px',
      viewportUnit: 'vmin',
      fontViewportUnit: 'vmin',
      propList: ['*'],
    }
  }
}
```

#### 主题包单位适配 (Viewport)

因为主题包是运行时挂载的，不受 postcss 影响，组件库提供了实用工具 `Themes.toViewport` 进行适配，函数返回的主题将默认使用 `375px -> 100vmin` 的规则。

```js
import { Themes } from '@varlet/ui'

const viewportTheme = Themes.toViewport(Themes.md3Dark)
```

也可以对转换规则进行更改

```js
import { Themes } from '@varlet/ui'

const viewportTheme = Themes.toViewport(Themes.md3Dark, {
  // 默认值为 375
  viewportWidth: 750,
  // 默认值为 'vmin'
  viewportUnit: 'vw',
  // 默认值为 6
  unitPrecision: 4,
})
```

####  主题包单位适配 (Rem)

与 `Viewport` 方案类似

```js
import { Themes } from '@varlet/ui'

const remTheme = Themes.toRem(Themes.md3Dark)
```

也支持自定义

```js
import { Themes } from '@varlet/ui'

const viewportTheme = Themes.toRem(Themes.md3Dark, {
  // 默认值为 16
  rootFontSize: 32,
  // 默认值为 6
  unitPrecision: 4,
})
```

### 桌面端适配

由于组件库交互事件使用 `touch` 事件进行开发，不支持桌面端的 `mouse` 事件，
推荐使用 `@varlet/touch-emulator` 将 `touch -> mouse` 从而实现桌面端适配。

```shell
# playground-ignore
# npm
npm i @varlet/touch-emulator
# yarn
yarn add @varlet/touch-emulator
# pnpm
pnpm add @varlet/touch-emulator
```

```js
// playground-ignore
import '@varlet/touch-emulator'
```

---

## File: packages/varlet-ui/docs/cli.en-US.md

# Components Library Tools

### Intro

The out-of-the-box `Vue3 component library` rapid prototyping tool provides a series of commands and tools to solve the problem of component library development.

### Features

- 📦 &nbsp;Out-of-the-box component library development environment
- 📦 &nbsp;An out-of-the-box component library compilation tool that supports exporting `esm`, `cjs`, `umd` module codes
- 🛠️ &nbsp;Configuration file-based component library documentation site, support Baidu statistics and theme customization
- 🛠️ &nbsp;Supports both `sfc` and `tsx` styles for writing component libraries
- 📦 &nbsp;Out-of-the-box code inspection tool
- 📦 &nbsp;Out-of-the-box unit testing tools
- 📦 &nbsp;Out-of-the-box code publishing tool, publishes to both `npm` and `github`, and automatically generates changelogs
- 💪 &nbsp;Support for `VSCode` extension development
- 💪 &nbsp;Support `build svg to web fonts`
- 💪 &nbsp;Support for `Typescript`
- 💪 &nbsp;Support `Various themes, including Material Design 2, Material Design 3`
- 🌍 &nbsp;Support `Internationalization`
- 🚀 &nbsp;Based on `pnpm`

### Recommended toolchain

Under Varlet’s current `component-library toolchain`, we recommend combining `@varlet/cli`, [`vite-plus`](https://viteplus.dev/) (`vp`), and [`rattail`](https://rattail.varletjs.org/) (`rt`): `@varlet/cli` covers first-party library workflows (docs, compile, tests, …), `vp` covers lint/format and app/extension build entrypoints aligned with the Oxc/Rolldown stack, and `rattail` covers `clean`, git hooks, `changelog`, `release`, `commit-lint`, and similar automation. Use this trio for new libraries and scaffold upgrades.

| Piece | Role |
| --- | --- |
| `@varlet/cli` | First-party Varlet workflows: `create`, `gen`, `dev`, `build`, `preview`, `compile`, `compile:style-vars`, `build:icons`, `test`, … |
| [`vite-plus`](https://viteplus.dev/) (`vp`) | Lint, format, app/extension `build`/`dev`/`preview`, and other toolchain entrypoints aligned with the Oxc/Rolldown stack |
| [`rattail`](https://rattail.varletjs.org/) (`rt`) | `clean`, git hooks, `changelog`, `release`, `commit-lint`, and other repo automation |

### Commands pending deprecation

These commands still run for backward compatibility and may print a deprecation notice. Do not rely on them in new scripts or new projects — prefer `vp` / `rt` (or `vr` where documented). Any future changes will be called out in release notes.

| Command | Use instead |
| --- | --- |
| `varlet-cli dev:vite` | `vp dev` |
| `varlet-cli build:vite` | `vp build` |
| `varlet-cli dev:extension` | `vp pack --watch` (with a local `vite.config.ts` for the extension) |
| `varlet-cli build:extension` | `vp pack` |
| `varlet-cli commit-lint` | `rt commit-lint` |
| `varlet-cli checklist` | Minimal value; deprecated without replacement |
| `varlet-cli changelog` | `rt changelog` |
| `varlet-cli release` | `rt release` |

### Quickstart

`@varlet/cli` has built-in `sfc` and `tsx` style component library project templates, which can be generated directly by the `gen` command.
It is convenient for you to directly enter the component library development.

```shell
# playground-ignore
pnpm add @varlet/cli -g
varlet-cli gen
```

## Advanced customization

### Configuration file

The `varlet.config.mjs` in the project root directory is used to manage the specific details of the entire component library project.
The default configuration can be viewed [varlet.default.config.ts](https://github.com/varletjs/varlet/blob/dev/packages/varlet-cli/src/node/config/varlet.default.config.ts).
Also refer to `@varlet/ui` [varlet.config.mjs](https://github.com/varletjs/varlet/blob/dev/packages/varlet-ui/varlet.config.mjs).

| Parameter | Description | Type | Default |
| --- | -------------- | -------- | ---------- |
| `name` | The full name of the component library, which will be used as the package name | _string_ | `Varlet` |
| `namespace` | Component library namespace, will be used as component prefix | _string_ | `var` |
| `host` | Development server host | _number_ | `localhost` |
| `port` | Development server port | _number_ | `8080` |
| `proxy` | Development server proxy | _Record<string, string \| ProxyOptions>_ | `-` |
| `title` | The title of the component library in the document | _string_ | `VARLET` |
| `logo` | The logo of the component library in the document | _string_ | `-` |
| `alias` | Path alias (root is src folder when use relative path) | _Record<string, string>_ | `-` |
| `defaultLanguage` | Document default language | _string_ | `zh-CN` |
| `defaultLightTheme` | The default light theme | _string_ | `md3LightTheme` |
| `defaultDarkTheme` | The default dark theme | _string_ | `md3DarkTheme` |
| `useMobile` | Whether to display the mobile phone preview on the right | _boolean_ | `false` |
| `themeKey` | The key of the theme in local storage | _string_ | `VARLET_THEME` |
| `lightTheme` | md2 light mode document theme | _Record<string, any>_ | `-` |
| `darkTheme` | md2 dark mode document theme | _Record<string, any>_ | `-` |
| `md3LightTheme` | md3 light mode document theme | _Record<string, any>_ | `-` |
| `md3DarkTheme` | md3 dark mode document theme | _Record<string, any>_ | `-` |
| `highlight` | Document code snippet style related | _{ style: string }_ | `-` |
| `analysis` | Document statistics related | _{ baidu: string }_ | `-` |
| `pc` | PC side document structure configuration | _[VarletConfigPc](https://github.com/varletjs/varlet/blob/dev/packages/varlet-cli/src/node/config/varlet.config.ts)_ | `-` |
| `mobile` | Mobile document structure configuration | _[VarletConfigMobile](https://github.com/varletjs/varlet/blob/dev/packages/varlet-cli/src/node/config/varlet.config.ts)_ | `-` |
| `bundle` | Bundle output options | _{ external: string[], globals: Record<string, string> }_ | `-` |
| `vitePlugins` | vite plugins | _[Plugin](https://vite.dev/guide/using-plugins.html)[]_ \| `(plugins: Plugin[]) => Plugin[])` | `-` |
| `directives` | Component library directive folder name | _string[]_ | `[]` |
| `copy` | Copy file configuration | _[CopyPath[]](https://github.com/varletjs/varlet/blob/dev/packages/varlet-vite-plugins/src/copy.ts)_ | `- ` |
| `icons` | Font icon packaging related configurations | _[VarletConfigIcons](https://github.com/varletjs/varlet/blob/dev/packages/varlet-cli/src/node/config/varlet.config.ts) _ | `-` |
| `esbuild` | esbuild configuration | _[VarletConfigEsbuild](https://github.com/varletjs/varlet/blob/dev/packages/varlet-cli/src/node/config/varlet.config.ts)_ | ` -` |
| `seo` | seo options | _[VarletConfigSeo](https://github.com/varletjs/varlet/blob/dev/packages/varlet-cli/src/node/config/varlet.config.ts)_ | ` -` |

#### Menu

| Parameter | Description | Type | Default |
| --- | -------------- | -------- | ---------- |
| `doc` | The document page corresponds to the matching file name, required | _string_ | `-` |
| `type` | The type of menu, when the type is `1`, it means the category menu, when the type is `2`, the doc field matches the component file under src, when the type is `3`, the doc field matches the md file under docs, required | _MenuTypes_ | `-` |
| `text` | The text displayed in the menu, English display text can be configured when internationalization is set, required | _Record<string, string>_ | `-` |
| `useMobile` | Whether to display the mobile phone preview on the right side on the current document page, if not filled, the default value is useMobile in config  | _boolean_ | `-` |

### Custom pages

If you want to insert other pages into the component library, you can create a `pages` folder in the project root directory to write a vue component to generate other pages.
The directory structure is as follows:

```text
// playground-ignore
|-- varlet-ui
  |-- src
  |-- docs
  |-- pages
    |-- sponsor
      |-- index.vue
    |-- contributor
      |-- locale
        |-- en-US.ts
      |-- index.vue
    |-- changelog
      |-- locale
        |-- zh-CN.ts
        |-- en-US.ts
      |-- index.vue
      
```

The resulting route is as follows:

```text
// playground-ignore
/zh-CN/sponsor
/en-US/contributor
/zh-CN/changelog
/en-US/changelog
```

### Command related

#### Start the development server

```shell
# playground-ignore
varlet-cli dev
# force mode
varlet-cli dev -f
# draft mode
varlet-cli dev -d
```

#### Build a documentation site

```shell
# playground-ignore
varlet-cli build
```

#### Preview documentation site

```shell
# playground-ignore
varlet-cli preview
```

#### Compile component library

```shell
# playground-ignore
varlet-cli compile
```

#### Compile style vars types declaration file

```shell
# playground-ignore
varlet-cli compile:style-vars
```

#### Build svg to web fonts

```shell
# playground-ignore
varlet-cli build:icons -w
varlet-cli build:icons
```

#### Execute all unit tests

```shell
# playground-ignore
varlet-cli test
```

#### Execute a unit test

```shell
# playground-ignore
varlet-cli test -c <componentName>
```

#### Execute unit tests in watch mode

```shell
# playground-ignore
varlet-cli test -w
```

#### Execute unit tests and report coverage

```shell
# playground-ignore
varlet-cli test -cov
```

#### Generate a project template

```shell
# playground-ignore
varlet-cli gen

# Options
-n
--name
  project name
-s
--sfc
  Generate sfc-style project templates
-t
--tsx
  Generate tsx-style project templates
-l
--locale
  Need to support internationalization
```

#### Create a component template file

```shell
# playground-ignore
varlet-cli create

# Options
-n
--name
  project name
-s
--sfc
  Generate sfc-style component
-t
--tsx
  Generate tsx-style component
-l
--locale
  Need to support internationalization
```

### Note before publish

1. `npm` repository registry must set to `npm` official mirror
2. Execute `npm login` to log in

### Q & A

#### How to solve failure of installing sharp ?

- You can choose to change mirror site which contains binaries for both sharp and libvips.

``` shell
pnpm config set sharp_binary_host "https://npmmirror.com/mirrors/sharp"
pnpm config set sharp_libvips_binary_host "https://npmmirror.com/mirrors/sharp-libvips"
```

---

## File: packages/varlet-ui/docs/cli.zh-CN.md

# 组件库快速成型工具

### 介绍

开箱即用的 `Vue3组件库` 快速成型工具，提供了一系列命令和工具去解决组件库开发上的问题。

### 特性

- 📦 &nbsp;开箱即用的组件库开发环境
- 📦 &nbsp;开箱即用的组件库编译工具，支持导出 `esm`, `cjs`, `umd` 三种模块代码
- 🛠️ &nbsp;基于配置文件的组件库文档站点，支持百度统计和主题定制
- 🛠️ &nbsp;支持 `sfc` 和 `tsx` 两种风格的组件库编写风格
- 📦 &nbsp;开箱即用的代码检查工具
- 📦 &nbsp;开箱即用的单元测试工具
- 📦 &nbsp;开箱即用的代码发布工具,同时发布到 `npm` 和 `github`, 并自动生成更新日志
- 💪 &nbsp;支持 `VSCode` 插件开发
- 💪 &nbsp;支持 `字体图标打包`
- 💪 &nbsp;支持 `Typescript`
- 💪 &nbsp;支持 `多种主题, 包含 Material Design 2、Material Design 3`
- 🌍 &nbsp;支持 `国际化`
- 🚀 &nbsp;基于 `pnpm`

### 推荐技术栈

在全新的 `Varlet 组件库工具链` 体系下，我们建议将 `@varlet/cli`、[`vite-plus`](https://viteplus.dev/)（`vp`）与 [`rattail`](https://rattail.varletjs.org/)（`rt`）组合使用：前者覆盖组件库文档站与编译等一等能力，后两者承接与 Oxc / Rolldown 栈一致的 lint、format、打包入口，以及 `clean`、git hooks、`changelog`、`release`、`commit-lint` 等工程自动化。无论是从零搭建新库，还是升级旧脚手架、需要与模板对齐时，都推荐沿用这一组合。

| 部分 | 作用 |
| --- | --- |
| `@varlet/cli` | Varlet 一等能力：`create`、`gen`、`dev`、`build`、`preview`、`compile`、`compile:style-vars`、`build:icons`、`test` 等 |
| [`vite-plus`](https://viteplus.dev/)（`vp`） | 与 Oxc / Rolldown 栈一致的 lint、format、应用/扩展的 `build`/`dev`/`preview` 等入口 |
| [`rattail`](https://rattail.varletjs.org/)（`rt`） | `clean`、git hooks、`changelog`、`release`、`commit-lint` 等工程自动化 |

### 以下命令即将废弃

以下命令仍可执行（会给出废弃相关提示），但不应在新脚本或新工程中再依赖，请优先改用 `vp` / `rt`（或文档中的 `vr`）。具体时间表以后续发布说明为准。

| 命令 | 请改用 |
| --- | --- |
| `varlet-cli dev:vite` | `vp dev` |
| `varlet-cli build:vite` | `vp build` |
| `varlet-cli dev:extension` | `vp pack --watch`（扩展包内需有本地 `vite.config.ts`） |
| `varlet-cli build:extension` | `vp pack` |
| `varlet-cli commit-lint` | `rt commit-lint` |
| `varlet-cli checklist` | 用处极小，直接废弃 |
| `varlet-cli changelog` | `rt changelog` |
| `varlet-cli release` | `rt release` |

### 快速开始

`@varlet/cli` 内置了 `sfc` 和 `tsx` 两种风格的组件库项目模板，可以通过 `gen` 命令直接生成。
方便您直接进入组件库开发。

```shell
# playground-ignore
pnpm add @varlet/cli -g
varlet-cli gen
```

## 高级定制

### 配置文件

项目根目录下的 `varlet.config.mjs` 用来管理整个组件库项目的具体细节。
默认配置可查阅 [varlet.default.config.ts](https://github.com/varletjs/varlet/blob/dev/packages/varlet-cli/src/node/config/varlet.default.config.ts)。
也可以参考 `@varlet/ui` 的 [varlet.config.mjs](https://github.com/varletjs/varlet/blob/dev/packages/varlet-ui/varlet.config.mjs)。

| 参数 | 说明 | 类型 | 默认值 |
| -- | -------------- | -------- | ---------- |
| `name` | 组件库全名，会作为包名 | _string_ | `Varlet` |
| `namespace` | 组件库命名空间, 会作为组件前缀 | _string_ | `var` |
| `host` | 开发服务器主机 | _number_ | `localhost` |
| `port` | 开发服务器端口 | _number_ | `8080` |
| `proxy` | 开发服务器代理 | _Record<string, string \| ProxyOptions>_ | `-` |
| `title` | 文档中组件库的标题 | _string_ | `VARLET` |
| `logo` | 文档中组件库的 logo | _string_ | `-` |
| `alias` | 路径别名 (使用相对路径时，根路径为 src 文件夹) | _Record<string, string>_ | `-` |
| `defaultLanguage` | 文档默认语言 | _string_ | `zh-CN` |
| `defaultLightTheme` | 默认的亮色主题 | _string_ | `md3LightTheme` |
| `defaultDarkTheme` | 默认的暗色主题 | _string_ | `md3DarkTheme` |
| `useMobile` | 是否显示右侧手机预览 | _boolean_ | `false` |
| `themeKey` | 主题在本地存储中的 key | _string_ | `VARLET_THEME` |
| `lightTheme` | md2 亮色模式文档主题 | _Record<string, any>_ | `-` |
| `darkTheme` | md2 暗黑模式文档主题 | _Record<string, any>_ | `-` |
| `md3LightTheme` | md3 亮色模式文档主题 | _Record<string, any>_ | `-` |
| `md3DarkTheme` | md3 暗黑模式文档主题 | _Record<string, any>_ | `-` |
| `highlight` | 文档代码片段样式相关 | _{ style: string }_ | `-` |
| `analysis` | 文档统计相关 | _{ baidu: string }_ | `-` |
| `pc` | pc 端文档结构配置 | _[VarletConfigPc](https://github.com/varletjs/varlet/blob/dev/packages/varlet-cli/src/node/config/varlet.config.ts)_ | `-` |
| `mobile` | mobile 端文档结构配置 | _[VarletConfigMobile](https://github.com/varletjs/varlet/blob/dev/packages/varlet-cli/src/node/config/varlet.config.ts)_ | `-` |
| `bundle` | 组件库编译的捆绑产物配置 | _{ external: string[], globals: Record<string, string> }_ | `-` |
| `vitePlugins` | vite 插件 | _[Plugin](https://vite.dev/guide/using-plugins.html)[]_ \| `(plugins: Plugin[]) => Plugin[])` | `-` |
| `directives` | 组件库指令文件夹名称 | _string[]_ | `[]` |
| `copy` | 复制文件配置 | _[CopyPath[]](https://github.com/varletjs/varlet/blob/dev/packages/varlet-vite-plugins/src/copy.ts)_ | `-` |
| `icons` | 字体图标打包相关配置 | _[VarletConfigIcons](https://github.com/varletjs/varlet/blob/dev/packages/varlet-cli/src/node/config/varlet.config.ts)_ | `-` |
| `esbuild` | esbuild 配置 | _[VarletConfigEsbuild](https://github.com/varletjs/varlet/blob/dev/packages/varlet-cli/src/node/config/varlet.config.ts)_ | `-` |
| `seo` | seo 选项 | _[VarletConfigSeo](https://github.com/varletjs/varlet/blob/dev/packages/varlet-cli/src/node/config/varlet.config.ts)_ | ` -` |

#### Menu

| 参数 | 说明 | 类型 | 默认值 |
| -- | -------------- | -------- | ---------- |
| `doc` | 文档页面应匹配的文件名称, 必填 | _string_ | `-` |
| `type` | menu 类型, 当 type 为 `1` 时表示分类 menu, 类型为 `2` 时 doc 字段匹配 src 下的组件文件, 类型为`3`时 doc 字段匹配 docs 下的 md 文件 | _MenuTypes_ | `-` |
| `text` | menu 所展示的文字, 当设置国际化时可配置英文展示文字 | _Record<string, string>_ | `-` |
| `useMobile` | 是否在当前文档页显示右侧手机预览, 如不填写, 默认取 config 中的 useMobile | _boolean_ | `-` |

### 自定义页面

如果想在组件库中插入其他页面，可以在项目根目录下的创建 `pages` 文件夹编写 vue 组件， 用来生成其他的页面。
目录结构如下：

```text
// playground-ignore
|-- varlet-ui
  |-- src
  |-- docs
  |-- pages
    |-- sponsor
      |-- index.vue
    |-- contributor
      |-- locale
        |-- en-US.ts
      |-- index.vue
    |-- changelog
      |-- locale
        |-- zh-CN.ts
        |-- en-US.ts
      |-- index.vue
```

生成的路由如下：

```text
// playground-ignore
/zh-CN/sponsor
/en-US/contributor
/zh-CN/changelog
/en-US/changelog
```

### 命令相关

#### 启动开发服务器

```shell
# playground-ignore
varlet-cli dev
# force mode
varlet-cli dev -f
# draft mode
varlet-cli dev -d
```

#### 构建文档站点

```shell
# playground-ignore
varlet-cli build
```

#### 预览文档站点

```shell
# playground-ignore
varlet-cli preview
```

#### 构建组件库

```shell
# playground-ignore
varlet-cli compile
```

#### 构建样式变量类型声明文件

```shell
# playground-ignore
varlet-cli compile:style-vars
```

#### 打包字体图标

```shell
# playground-ignore
varlet-cli build:icons -w
varlet-cli build:icons
```

#### 执行所有的单元测试

```shell
# playground-ignore
varlet-cli test
```

#### 执行单个组件的单元测试

```shell
# playground-ignore
varlet-cli test -c <componentName>
```

#### 以 watch 模式执行单元测试

```shell
# playground-ignore
varlet-cli test -w
```

#### 执行所有的单元测试并报告覆盖率

```shell
# playground-ignore
varlet-cli test -cov
```

#### 生成一个项目模板

```shell
# playground-ignore
varlet-cli gen

# Options
-n
--name
  项目名
-s
--sfc
  生成 sfc 风格的项目模板
-t
--tsx
  生成 tsx 格式项目
-l
--locale
  需要支持国际化
```

#### 创建组件模板文件

```shell
# playground-ignore
varlet-cli create

# Options
-n
--name
  组件名
-s
--sfc
  生成 sfc 风格的组件
-t
--tsx
  生成 tsx 风格的文件
-l
--locale
  需要支持国际化
```

### 发布前注意

1. `npm` 的仓库源必须指向 `npm` 官方镜像
2. 执行 `npm login` 进行登录

### 问答

#### 如何解决安装 sharp 失败的问题 ?

- 您可以选择更改包含 sharp 和 libvips 二进制文件的镜像站点

``` shell
pnpm config set sharp_binary_host "https://npmmirror.com/mirrors/sharp"
pnpm config set sharp_libvips_binary_host "https://npmmirror.com/mirrors/sharp-libvips"
```