vue-vben-admin Documentation

File: README.md Copy Chapter

English | 中文 | 日本語

Introduction Copy Chapter

Vue Vben Admin is a free and open source middle and back-end template. Using the latest vue3, vite, TypeScript and other mainstream technology development, the out-of-the-box middle and back-end front-end solutions can also be used for learning reference.

Upgrade Notice Copy Chapter

This is the latest version, 5.0, and it is not compatible with previous versions. If you are starting a new project, it is recommended to use the latest version. If you wish to view the old version, please use the v2 branch.

Features Copy Chapter

• Latest Technology Stack: Developed with cutting-edge front-end technologies like Vue 3 and Vite
• TypeScript: A language for application-scale JavaScript
• Themes: Multiple theme colors available with customizable options
• Internationalization: Comprehensive built-in internationalization support
• Permissions: Built-in solution for dynamic route-based permission generation

Preview Copy Chapter

• Vben Admin - Full version Chinese site

Test Account: vben/123456

Use Gitpod Copy Section

Open the project in Gitpod (free online dev environment for GitHub) and start coding immediately.

Documentation Copy Chapter

Document

Install and Use Copy Chapter

1. Get the project code

git clone https://github.com/vbenjs/vue-vben-admin.git

2. Install dependencies

cd vue-vben-admin
npm i corepack
pnpm install

3. Run

pnpm dev

4. Build

pnpm build

Change Log Copy Chapter

CHANGELOG

How to Contribute Copy Chapter

You are very welcome to join! Raise an issue or submit a Pull Request.

Pull Request Process:

1. Fork the code
2. Create your branch: git checkout -b feat/xxxx
3. Submit your changes: git commit -am 'feat(function): add xxxxx'
4. Push your branch: git push origin feat/xxxx
5. Submit pull request

Git Contribution Submission Specification Copy Chapter

Reference vue specification (Angular)

• feat Add new features
• fix Fix the problem/BUG
• style The code style is related and does not affect the running result
• perf Optimization/performance improvement
• refactor Refactor
• revert Undo edit
• test Test related
• docs Documentation/notes
• chore Dependency update/scaffolding configuration modification etc.
• ci Continuous integration
• types Type definition file changes

Browser Support Copy Chapter

Tailwind CSS v4.0 is designed for Safari 16.4+, Chrome 111+, and Firefox 128+

Support modern browsers, not IE

Maintainer Copy Chapter

@Vben

Star History Copy Chapter

Donate Copy Chapter

If you think this project is helpful to you, you can help the author buy a cup of coffee to show your support!

Paypal Me

Contributors Copy Chapter

Discord Copy Chapter

• Github Discussions

License Copy Chapter

MIT © Vben-2020

File: apps/backend-mock/README.md Copy Chapter

@vben/backend-mock

Description Copy Chapter

Vben Admin 数据 mock 服务，没有对接任何的数据库，所有数据都是模拟的，用于前端开发时提供数据支持。线上环境不再提供 mock 集成，可自行部署服务或者对接真实数据，由于 mock.js 等工具有一些限制，比如上传文件不行、无法模拟复杂的逻辑等，所以这里使用了真实的后端服务来实现。唯一麻烦的是本地需要同时启动后端服务和前端服务，但是这样可以更好的模拟真实环境。该服务不需要手动启动，已经集成在 vite 插件内，随应用一起启用。

Running the app Copy Chapter

# development
$ pnpm run start

# production mode
$ pnpm run build

File: docs/src/guide/project/changeset.md Copy Chapter

Changeset

项目内置了 changeset 作为版本管理工具。Changeset 是一个版本管理工具，它可以帮助我们更好的管理版本，生成 changelog，以及自动发布。

详细使用方式可查看官方文档，这里不再阐述。如果你不需要它，可以直接忽略。

命令行 Copy Chapter

changeset 命令在项目中已经内置：

交互式填写变更集 Copy Section

pnpm run changeset

统一提升版本号 Copy Section

pnpm run version

File: docs/src/guide/project/cli.md Copy Chapter

outline: deep Copy Chapter

CLI

项目中，提供了一些命令行工具，用于一些常用的操作，代码位于 scrips 内。

vsh Copy Chapter

用于一些项目操作，如清理项目、检查项目等。

用法 Copy Section

pnpm vsh [command] [options]

vsh check-circular Copy Section

检查整个项目循环引用，如果有循环引用，会在控制台输出循环引用的模块。

用法

pnpm vsh check-circular

选项

vsh check-dep Copy Section

检查整个项目依赖情况，并在控制台输出未使用的依赖、未安装的依赖信息

用法

pnpm vsh check-dep

选项

vsh lint Copy Section

对项目进行lint检查，检查项目中的代码是否符合规范。

用法

pnpm vsh lint

选项

vsh publint Copy Section

对 Monorepo 项目进行包规范检查，检查项目中的包是否符合规范。

用法

pnpm vsh publint

选项

vsh code-workspace Copy Section

生成 vben-admin.code-workspace 文件，目前不需要手动执行，会在代码提交时自动执行。

用法

pnpm vsh code-workspace

选项

turbo-run Copy Chapter

用于快速执行大仓中脚本，并提供选项式交互选择。

用法 Copy Section

pnpm turbo-run [command]

turbo-run dev Copy Section

快速执行dev命令，并提供选项式交互选择。

File: docs/src/guide/project/dir.md Copy Chapter

目录说明

目录使用 Monorepo 管理，项目结构如下：

/* Detailed source-code truncated for AI context efficiency. */

File: docs/src/guide/project/standard.md Copy Chapter

规范

::: tip 贡献代码

• 如果你想向项目贡献代码，请确保你的代码符合项目的代码规范。
• 如果你使用的是 vscode，需要安装以下插件：
  • ESLint - 脚本代码检查
  • Oxc - Oxlint / Oxfmt 集成
  • Code Spell Checker - 单词语法检查
  • Stylelint - CSS 格式检查

:::

作用 Copy Chapter

具备基本工程素养的同学都会注重编码规范，而代码风格检查（Code Linting，简称 Lint）是保障代码规范一致性的重要手段。

遵循相应的代码规范有以下好处：

• 较少 bug 错误率
• 高效的开发效率
• 更高的可读性

工具 Copy Chapter

项目的配置文件位于 internal/lint-configs 下，你可以在这里修改各种 lint 的配置。

项目内集成了以下几种代码校验工具：

• Oxfmt 用于代码格式化
• Oxlint 用于 JavaScript / TypeScript 代码检查
• ESLint 用于 Vue、JSONC、YAML 等规则检查
• Stylelint 用于 CSS 样式检查
• Commitlint 用于检查 git 提交信息的规范
• Publint 用于检查 npm 包的规范
• Cspell 用于检查拼写错误
• lefthook 用于管理 Git hooks，在提交前自动运行代码校验和格式化

Oxfmt Copy Chapter

Oxfmt 用于统一项目代码风格，统一缩进、引号、尾逗号等格式。

命令 Copy Section

pnpm oxfmt
pnpm oxfmt --check

配置 Copy Section

Oxfmt 的根目录入口文件为 oxfmt.config.ts，其核心配置位于 internal/lint-configs/oxfmt-config 目录下，可以根据项目需求进行修改。

Oxlint Copy Chapter

Oxlint 是当前仓库的主要脚本 lint 工具，用于识别和报告 JavaScript / TypeScript 代码中的问题。

命令 Copy Section

pnpm oxlint
pnpm oxlint --fix

配置 Copy Section

Oxlint 的核心配置位于 internal/lint-configs/oxlint-config 目录下，根目录入口文件为 oxlint.config.ts。

ESLint Copy Chapter

ESLint 用于补充 Vue、JSONC、YAML 等规则检查。

命令 Copy Section

pnpm eslint . --cache

配置 Copy Section

ESLint 配置文件为 eslint.config.mjs，其核心配置放在 internal/lint-configs/eslint-config 目录下，可以根据项目需求进行修改。

Stylelint Copy Chapter

Stylelint 用于校验项目内部 CSS 的风格，加上编辑器的自动修复，可以很好的统一项目内部 CSS 风格。

命令 Copy Section

pnpm stylelint "**/*.{vue,css,less,scss}" --cache

配置 Copy Section

Stylelint 配置文件为 stylelint.config.mjs，其核心配置放在 internal/lint-configs/stylelint-config 目录下，可以根据项目需求进行修改。

CommitLint Copy Chapter

在一个团队中，每个人的 git 的 commit 信息都不一样，五花八门，没有一个机制很难保证规范化，如何才能规范化呢？可能你想到的是 git 的 hook 机制，去写 shell 脚本去实现。这当然可以，其实 JavaScript 有一个很好的工具可以实现这个模板，它就是 commitlint（用于校验 git 提交信息规范）。

配置 Copy Section

CommitLint 配置文件为 .commitlintrc.js，其核心配置放在 internal/lint-configs/commitlint-config 目录下，可以根据项目需求进行修改。

Git 提交规范 Copy Section

参考 Angular

• feat 增加新功能
• fix 修复问题 / BUG
• style 代码风格相关无影响运行结果的
• perf 优化 / 性能提升
• refactor 重构
• revert 撤销修改
• test 测试相关
• docs 文档 / 注释
• chore 依赖更新 / 脚手架配置修改等
• workflow 工作流改进
• ci 持续集成
• types 类型修改

关闭 Git 提交规范检查 Copy Section

如果你想关闭 Git 提交规范检查，有两种方式：

::: code-group

git commit -m 'feat: add home page' --no-verify

commit-msg:
  commands:
    # commitlint:
    #   run: pnpm exec commitlint --edit $1

:::

如果修改了 lefthook.yml，请重新执行：

pnpm exec lefthook install

Publint Copy Chapter

Publint 是一个用于检查 npm 包规范的工具，可以检查包的版本号、导出方式以及 ESM 包结构等问题。

命令 Copy Section

pnpm publint

Cspell Copy Chapter

Cspell 是一个用于检查拼写错误的工具，可以检查代码中的拼写错误，避免因为拼写错误导致的 bug。

命令 Copy Section

pnpm check:cspell

配置 Copy Section

cspell 配置文件为 cspell.json，可以根据项目需求进行修改。

Git Hook Copy Chapter

git hook 一般结合各种 lint，在 git 提交代码的时候进行代码风格校验，如果校验没通过，则不会进行提交。需要开发者自行修改后再次进行提交。

lefthook Copy Section

有一个问题就是校验会校验全部代码，但是我们只想校验我们自己提交的代码，这个时候就可以使用 lefthook。

最有效的解决方案就是将 lint 校验放到本地，常见做法是使用 lefthook 在本地提交之前先做一次 lint 校验。

项目在 lefthook.yml 内部定义了相应的 hooks：

• pre-commit: 在提交前运行，用于代码格式化和检查
  • code-workspace: 更新 VSCode 工作区配置
  • lint-md: 格式化 Markdown 文件
  • lint-vue: 格式化并检查 Vue 文件
  • lint-js: 格式化并检查 JavaScript / TypeScript 文件
  • lint-style: 格式化并检查样式文件
  • lint-package: 格式化 package.json
  • lint-json: 格式化其他 JSON 文件
• post-merge: 在合并后运行，用于自动安装依赖
  • install: 运行 pnpm install 安装新依赖
• commit-msg: 在提交时运行，用于检查提交信息格式
  • commitlint: 使用 commitlint 检查提交信息

当前 hooks 可通过以下命令安装：

pnpm exec lefthook install

如何关闭 lefthook

如果你想临时关闭 lefthook，可以使用：

git commit -m 'feat: add home page' --no-verify

如何修改 lefthook 配置

如果你想修改 lefthook 的配置，可以编辑 lefthook.yml 文件。例如：

pre-commit:
  parallel: true
  commands:
    lint-js:
      run: pnpm oxfmt {staged_files} && pnpm oxlint --fix {staged_files} && pnpm eslint --cache --fix {staged_files}
      glob: '*.{js,jsx,ts,tsx}'

其中：

• parallel: 是否并行执行任务
• commands: 定义要执行的任务列表
• run: 要执行的命令
• glob: 匹配的文件模式
• {staged_files}: 表示暂存的文件列表

File: docs/src/guide/project/tailwindcss.md Copy Chapter

Tailwind CSS

Tailwind CSS 是一个实用性优先的 CSS 框架，用于快速构建自定义设计。当前项目使用的是 Tailwind CSS v4。

配置 Copy Chapter

项目当前不再通过 tailwind.config.* 文件维护 Tailwind 配置，主题与扫描范围都统一放在 CSS 与共享 Vite 配置中。

• 主题入口：internal/tailwind-config/src/theme.css
• Vite 集成：internal/vite-config

在 global.css 中你会看到当前项目使用的 Tailwind CSS v4 指令，例如：

• @source
• @custom-variant
• @theme
• @theme inline
• @utility

包使用 Tailwind CSS 的方式 Copy Chapter

当前项目不会根据某个包下是否存在 tailwind.config.mjs 来决定是否启用 Tailwind CSS。

应用和包统一复用 @vben/vite-config，并由该配置接入 @tailwindcss/vite。Tailwind 的扫描范围则统一在 @vben/tailwind-config 对应的 internal/tailwind-config/src/theme.css 中维护。

::: tip 包使用 Tailwind CSS 的说明

如果你是纯粹的 SDK 包，不需要使用 Tailwind CSS，则无需额外增加旧版 tailwind.config.* 文件。

:::

Vue SFC 中的 `@apply` Copy Chapter

项目对 Vue 单文件组件中的 @apply 做了统一处理，相关逻辑位于：

• internal/vite-config/src/plugins/tailwind-reference.ts

当组件样式中使用 @apply 时，会自动注入 @reference "@vben/tailwind-config/theme"，一般不需要手动补充。