mirror of
https://github.com/imdap/ruoyi-plus-vben5.git
synced 2026-05-07 02:31:58 +08:00
docs(@vben/docs): align guide docs with current tooling
This commit is contained in:
xingyu4j
@@ -24,18 +24,18 @@
|
||||
|
||||
### 工具配置
|
||||
|
||||
如果您使用的 IDE 是[vscode](https://code.visualstudio.com/)(推荐)的话，可以安装以下工具来提高开发效率及代码格式化:
|
||||
如果您使用的 IDE 是 [vscode](https://code.visualstudio.com/)（推荐）的话，可以安装以下工具来提高开发效率及代码格式化:
|
||||
|
||||
- [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) - Vue 官方插件（必备）。
|
||||
- [Tailwind CSS](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) - Tailwindcss 提示插件。
|
||||
- [CSS Variable Autocomplete](https://marketplace.visualstudio.com/items?itemName=bradlc.vunguyentuan.vscode-css-variables) - Css 变量提示插件。
|
||||
- [Iconify IntelliSense](https://marketplace.visualstudio.com/items?itemName=antfu.iconify) - Iconify 图标插件
|
||||
- [i18n Ally](https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally) - i18n 插件
|
||||
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - 脚本代码检查
|
||||
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - 代码格式化
|
||||
- [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - css 格式化
|
||||
- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - 单词语法检查
|
||||
- [DotENV](https://marketplace.visualstudio.com/items?itemName=mikestead.dotenv) - .env 文件 高亮
|
||||
- [CSS Variable Autocomplete](https://marketplace.visualstudio.com/items?itemName=vunguyentuan.vscode-css-variables) - CSS 变量提示插件。
|
||||
- [Iconify IntelliSense](https://marketplace.visualstudio.com/items?itemName=antfu.iconify) - Iconify 图标插件。
|
||||
- [i18n Ally](https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally) - i18n 插件。
|
||||
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - 脚本代码检查。
|
||||
- [Oxc](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) - Oxlint / Oxfmt 集成。
|
||||
- [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - CSS 格式检查。
|
||||
- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - 单词语法检查。
|
||||
- [DotENV](https://marketplace.visualstudio.com/items?itemName=mikestead.dotenv) - `.env` 文件高亮。
|
||||
|
||||
## Npm Scripts
|
||||
|
||||
@@ -51,15 +51,17 @@ npm 脚本是项目常见的配置，用于执行一些常见的任务，比如
|
||||
// 构建项目并分析
|
||||
"build:analyze": "turbo build:analyze",
|
||||
// 构建本地 docker 镜像
|
||||
"build:docker": "./build-local-docker-image.sh",
|
||||
"build:docker": "./scripts/deploy/build-local-docker-image.sh",
|
||||
// 单独构建 web-antd 应用
|
||||
"build:antd": "pnpm run build --filter=@vben/web-antd",
|
||||
// 单独构建 web-antdv-next 应用
|
||||
"build:antdv-next": "pnpm run build --filter=@vben/web-antdv-next",
|
||||
// 单独构建文档
|
||||
"build:docs": "pnpm run build --filter=@vben/docs",
|
||||
// 单独构建 web-ele 应用
|
||||
"build:ele": "pnpm run build --filter=@vben/web-ele",
|
||||
// 单独构建 web-naive 应用
|
||||
"build:naive": "pnpm run build --filter=@vben/naive",
|
||||
"build:naive": "pnpm run build --filter=@vben/web-naive",
|
||||
// 单独构建 web-tdesign 应用
|
||||
"build:tdesign": "pnpm run build --filter=@vben/web-tdesign",
|
||||
// 单独构建 playground 应用
|
||||
@@ -71,48 +73,54 @@ npm 脚本是项目常见的配置，用于执行一些常见的任务，比如
|
||||
// 检查循环引用
|
||||
"check:circular": "vsh check-circular",
|
||||
// 检查拼写
|
||||
"check:cspell": "cspell lint **/*.ts **/README.md .changeset/*.md --no-progress"
|
||||
"check:cspell": "cspell lint **/*.ts **/README.md .changeset/*.md --no-progress",
|
||||
// 检查依赖
|
||||
"check:dep": "vsh check-dep",
|
||||
// 检查类型
|
||||
"check:type": "turbo run typecheck",
|
||||
// 清理项目（删除node_modules、dist、.turbo）等目录
|
||||
// 清理项目（删除 node_modules、dist、.turbo）等目录
|
||||
"clean": "node ./scripts/clean.mjs",
|
||||
// 提交代码
|
||||
"commit": "czg",
|
||||
// 启动项目（默认会运行整个仓库所有包的dev脚本）
|
||||
// 启动项目（默认会运行整个仓库所有包的 dev 脚本）
|
||||
"dev": "turbo-run dev",
|
||||
// 启动web-antd应用
|
||||
// 启动 web-antd 应用
|
||||
"dev:antd": "pnpm -F @vben/web-antd run dev",
|
||||
// 启动 web-antdv-next 应用
|
||||
"dev:antdv-next": "pnpm -F @vben/web-antdv-next run dev",
|
||||
// 启动文档
|
||||
"dev:docs": "pnpm -F @vben/docs run dev",
|
||||
// 启动web-ele应用
|
||||
// 启动 web-ele 应用
|
||||
"dev:ele": "pnpm -F @vben/web-ele run dev",
|
||||
// 启动web-naive应用
|
||||
// 启动 web-naive 应用
|
||||
"dev:naive": "pnpm -F @vben/web-naive run dev",
|
||||
// 启动 web-tdesign 应用
|
||||
"dev:tdesign": "pnpm -F @vben/web-tdesign run dev",
|
||||
// 启动演示应用
|
||||
"dev:play": "pnpm -F @vben/playground run dev",
|
||||
// 格式化代码
|
||||
"format": "vsh lint --format",
|
||||
// lint 代码
|
||||
"lint": "vsh lint",
|
||||
// 依赖安装完成之后，执行所有包的stub脚本
|
||||
// 依赖安装完成之后，执行所有包的 stub 脚本
|
||||
"postinstall": "pnpm -r run stub --if-present",
|
||||
// 只允许使用pnpm
|
||||
// 只允许使用 pnpm
|
||||
"preinstall": "npx only-allow pnpm",
|
||||
// lefthook的安装
|
||||
"prepare": "is-ci || lefthook install",
|
||||
// 安装 lefthook
|
||||
"prepare": "pnpm exec lefthook install",
|
||||
// 预览应用
|
||||
"preview": "turbo-run preview",
|
||||
// 包规范检查
|
||||
"publint": "vsh publint",
|
||||
// 删除所有的node_modules、yarn.lock、package.lock.json，重新安装依赖
|
||||
// 删除所有的 node_modules、yarn.lock、package-lock.json，重新安装依赖
|
||||
"reinstall": "pnpm clean --del-lock && pnpm install",
|
||||
// 运行 e2e 测试
|
||||
"test:e2e": "turbo run test:e2e",
|
||||
// 运行 vitest 单元测试
|
||||
"test:unit": "vitest run --dom",
|
||||
// 更新项目依赖
|
||||
"update:deps": " pnpm update --latest --recursive",
|
||||
// changeset生成提交集
|
||||
"update:deps": "npx taze -r -w",
|
||||
// changeset 生成提交集
|
||||
"version": "pnpm exec changeset version && pnpm install --no-frozen-lockfile"
|
||||
}
|
||||
}
|
||||
@@ -134,6 +142,12 @@ pnpm dev
|
||||
pnpm dev:antd
|
||||
```
|
||||
|
||||
运行 `web-antdv-next` 应用：
|
||||
|
||||
```bash
|
||||
pnpm dev:antdv-next
|
||||
```
|
||||
|
||||
运行 `web-naive` 应用：
|
||||
|
||||
```bash
|
||||
@@ -146,6 +160,12 @@ pnpm dev:naive
|
||||
pnpm dev:ele
|
||||
```
|
||||
|
||||
运行 `web-tdesign` 应用：
|
||||
|
||||
```bash
|
||||
pnpm dev:tdesign
|
||||
```
|
||||
|
||||
运行 `docs` 应用：
|
||||
|
||||
```bash
|
||||
@@ -154,11 +174,11 @@ pnpm dev:docs
|
||||
|
||||
## 区分构建环境
|
||||
|
||||
在实际的业务开发中，通常会在构建时区分多种环境，如测试环境`test`、生产环境`build`等。
|
||||
在实际的业务开发中，通常会在构建时区分多种环境，如测试环境 `test`、生产环境 `build` 等。
|
||||
|
||||
此时可以修改三个文件，在其中增加对应的脚本配置来达到区分生产环境的效果。
|
||||
|
||||
以`@vben/web-antd`添加测试环境`test`为例：
|
||||
以 `@vben/web-antd` 添加测试环境 `test` 为例：
|
||||
|
||||
- `apps\web-antd\package.json`
|
||||
|
||||
@@ -173,7 +193,7 @@ pnpm dev:docs
|
||||
},
|
||||
```
|
||||
|
||||
增加命令`"build:test"`, 并将原`"build"`改为`"build:prod"`以避免同时构建两个环境的包。
|
||||
增加命令 `"build:test"`，并将原 `"build"` 改为 `"build:prod"` 以避免同时构建两个环境的包。
|
||||
|
||||
- `package.json`
|
||||
|
||||
@@ -188,7 +208,7 @@ pnpm dev:docs
|
||||
}
|
||||
```
|
||||
|
||||
在根目录`package.json`中加入构建测试环境的命令
|
||||
在根目录 `package.json` 中加入构建测试环境的命令。
|
||||
|
||||
- `turbo.json`
|
||||
|
||||
@@ -217,17 +237,17 @@ pnpm dev:docs
|
||||
······
|
||||
```
|
||||
|
||||
在`turbo.json`中加入相关依赖的命令
|
||||
在 `turbo.json` 中加入相关依赖的命令。
|
||||
|
||||
## 公共静态资源
|
||||
|
||||
项目中需要使用到的公共静态资源，如：图片、静态HTML等，需要在开发中通过 `src="/xxx.png"` 直接引入的。
|
||||
项目中需要使用到的公共静态资源，如：图片、静态 HTML 等，需要在开发中通过 `src="/xxx.png"` 直接引入的。
|
||||
|
||||
需要将资源放在对应项目的 `public/static` 目录下。引入的路径为：`src="/static/xxx.png"`。
|
||||
|
||||
## DevTools
|
||||
|
||||
项目内置了 [Vue DevTools](https://github.com/vuejs/devtools-next) 插件，可以在开发过程中使用。默认关闭，可在`.env.development` 内开启，并重新运行项目即可：
|
||||
项目内置了 [Vue DevTools](https://github.com/vuejs/devtools-next) 插件，可以在开发过程中使用。默认关闭，可在 `.env.development` 内开启，并重新运行项目即可：
|
||||
|
||||
```bash
|
||||
VITE_DEVTOOLS=true
|
||||
@@ -251,7 +271,7 @@ pnpm dev:docs
|
||||
|
||||
```bash
|
||||
# 请在项目根目录下执行
|
||||
# 该命令会删除整个仓库所有的 node_modules、yarn.lock、package.lock.json后
|
||||
# 该命令会删除整个仓库所有的 node_modules、yarn.lock、package-lock.json 后
|
||||
# 再进行依赖重新安装（安装速度会明显变慢）。
|
||||
pnpm reinstall
|
||||
```
|
||||
|
||||
@@ -20,9 +20,9 @@
|
||||
- **动态菜单**：支持动态菜单，可以根据权限配置显示菜单。
|
||||
- **Mock 数据**：基于 `Nitro` 的本地高性能 Mock 数据方案。
|
||||
- **组件丰富**：提供了丰富的组件，可以满足大部分的业务需求。
|
||||
- **规范**：代码规范，使用 `ESLint`、`Prettier`、`Stylelint`、`Publint`、`CSpell` 等工具保证代码质量。
|
||||
- **工程化**：使用 `Pnpm Monorepo`、`TurboRepo`、`Changeset` 等工具，提高开发效率。
|
||||
- **多UI库支持**：支持 `Ant Design Vue`、`Element Plus`、`Naive` 等主流 UI 库，不再限制于特定框架。
|
||||
- **规范**：代码规范，使用 `Oxfmt`、`Oxlint`、`ESLint`、`Stylelint`、`Publint`、`CSpell` 等工具保证代码质量。
|
||||
- **工程化**：使用 `Pnpm Monorepo`、`Turborepo`、`Changeset` 等工具，提高开发效率。
|
||||
- **多UI库支持**：支持 `Ant Design Vue`、`Ant Design Vue Next`、`Element Plus`、`Naive UI`、`TDesign` 等主流 UI 库，不再限制于特定框架。
|
||||
|
||||
## 浏览器支持
|
||||
|
||||
|
||||
@@ -20,4 +20,4 @@
|
||||
|
||||
## 质量与规范
|
||||
|
||||
我们始终高度重视代码的质量与规范。通过使用 ESLint、Prettier、Stylelint、Publint、CSpell 等工具来确保代码质量。我们的代码规范基于 Vue3、Vite、TypeScript 等现代前端技术制定，旨在提供一个简洁、易用的框架，使开发者能够快速上手并专注于业务逻辑的开发。
|
||||
我们始终高度重视代码的质量与规范。通过使用 Oxfmt、Oxlint、ESLint、Stylelint、Publint、CSpell 等工具来确保代码质量。我们的代码规范基于 Vue3、Vite、TypeScript 等现代前端技术制定，旨在提供一个简洁、易用的框架，使开发者能够快速上手并专注于业务逻辑的开发。
|
||||
|
||||
@@ -4,65 +4,69 @@
|
||||
|
||||
```bash
|
||||
.
|
||||
├── Dockerfile # Docker 镜像构建文件
|
||||
├── README.md # 项目说明文档
|
||||
├── apps # 项目应用目录
|
||||
│ ├── backend-mock # 后端模拟服务应用
|
||||
│ ├── web-antd # 基于 Ant Design Vue 的前端应用
|
||||
│ ├── web-ele # 基于 Element Plus 的前端应用
|
||||
│ └── web-naive # 基于 Naive UI 的前端应用
|
||||
├── build-local-docker-image.sh # 本地构建 Docker 镜像脚本
|
||||
│ ├── backend-mock # 后端模拟服务应用
|
||||
│ ├── web-antd # 基于 Ant Design Vue 的前端应用
|
||||
│ ├── web-antdv-next # 基于 Ant Design Vue Next 的前端应用
|
||||
│ ├── web-ele # 基于 Element Plus 的前端应用
|
||||
│ ├── web-naive # 基于 Naive UI 的前端应用
|
||||
│ └── web-tdesign # 基于 TDesign 的前端应用
|
||||
├── cspell.json # CSpell 配置文件
|
||||
├── docs # 项目文档目录
|
||||
├── eslint.config.mjs # ESLint 配置文件
|
||||
├── lefthook.yml # Git Hook 配置文件
|
||||
├── internal # 内部工具目录
|
||||
│ ├── lint-configs # 代码检查配置
|
||||
│ │ ├── commitlint-config # Commitlint 配置
|
||||
│ │ ├── eslint-config # ESLint 配置
|
||||
│ │ ├── prettier-config # Prettier 配置
|
||||
│ │ └── stylelint-config # Stylelint 配置
|
||||
│ ├── node-utils # Node.js 工具
|
||||
│ ├── tailwind-config # Tailwind 配置
|
||||
│ ├── tsconfig # 通用 tsconfig 配置
|
||||
│ └── vite-config # 通用Vite 配置
|
||||
│ ├── lint-configs # 代码检查配置
|
||||
│ │ ├── commitlint-config # Commitlint 配置
|
||||
│ │ ├── eslint-config # ESLint 配置
|
||||
│ │ ├── oxfmt-config # Oxfmt 配置
|
||||
│ │ ├── oxlint-config # Oxlint 配置
|
||||
│ │ └── stylelint-config # Stylelint 配置
|
||||
│ ├── node-utils # Node.js 工具
|
||||
│ ├── tsconfig # 通用 tsconfig 配置
|
||||
│ └── vite-config # 通用 Vite 配置
|
||||
├── oxfmt.config.ts # Oxfmt 配置入口
|
||||
├── oxlint.config.ts # Oxlint 配置文件
|
||||
├── package.json # 项目依赖配置
|
||||
├── packages # 项目包目录
|
||||
│ ├── @core # 核心包
|
||||
│ │ ├── base # 基础包
|
||||
│ │ │ ├── design # 设计相关
|
||||
│ │ │ ├── icons # 图标
|
||||
│ │ │ ├── shared # 共享
|
||||
│ │ │ └── typings # 类型定义
|
||||
│ │ ├── composables # 组合式 API
|
||||
│ │ ├── preferences # 偏好设置
|
||||
│ │ └── ui-kit # UI 组件集合
|
||||
│ │ ├── layout-ui # 布局 UI
|
||||
│ │ ├── menu-ui # 菜单 UI
|
||||
│ │ ├── shadcn-ui # shadcn UI
|
||||
│ │ └── tabs-ui # 标签页 UI
|
||||
│ ├── constants # 常量
|
||||
│ ├── effects # 副作用相关包
|
||||
│ │ ├── access # 访问控制
|
||||
│ │ ├── plugins # 第三方大型依赖插件
|
||||
│ │ ├── common-ui # 通用 UI
|
||||
│ │ ├── hooks # 组合式 API
|
||||
│ │ ├── layouts # 布局
|
||||
│ │ └── request # 请求
|
||||
│ ├── icons # 图标
|
||||
│ ├── locales # 国际化
|
||||
│ ├── preferences # 偏好设置
|
||||
│ ├── stores # 状态管理
|
||||
│ ├── styles # 样式
|
||||
│ ├── types # 类型定义
|
||||
│ └── utils # 工具
|
||||
│ ├── @core # 核心包
|
||||
│ │ ├── base # 基础包
|
||||
│ │ │ ├── design # 设计相关
|
||||
│ │ │ ├── icons # 图标
|
||||
│ │ │ ├── shared # 共享
|
||||
│ │ │ └── typings # 类型定义
|
||||
│ │ ├── composables # 组合式 API
|
||||
│ │ ├── preferences # 偏好设置
|
||||
│ │ └── ui-kit # UI 组件集合
|
||||
│ │ ├── layout-ui # 布局 UI
|
||||
│ │ ├── menu-ui # 菜单 UI
|
||||
│ │ ├── shadcn-ui # shadcn UI
|
||||
│ │ └── tabs-ui # 标签页 UI
|
||||
│ ├── constants # 常量
|
||||
│ ├── effects # 副作用相关包
|
||||
│ │ ├── access # 访问控制
|
||||
│ │ ├── plugins # 第三方大型依赖插件
|
||||
│ │ ├── common-ui # 通用 UI
|
||||
│ │ ├── hooks # 组合式 API
|
||||
│ │ ├── layouts # 布局
|
||||
│ │ └── request # 请求
|
||||
│ ├── icons # 图标
|
||||
│ ├── locales # 国际化
|
||||
│ ├── preferences # 偏好设置
|
||||
│ ├── stores # 状态管理
|
||||
│ ├── styles # 样式
|
||||
│ ├── types # 类型定义
|
||||
│ └── utils # 工具
|
||||
├── playground # 演示目录
|
||||
├── pnpm-lock.yaml # pnpm 锁定文件
|
||||
├── pnpm-workspace.yaml # pnpm 工作区配置文件
|
||||
├── scripts # 脚本目录
|
||||
│ ├── turbo-run # Turbo 运行脚本
|
||||
│ └── vsh # VSH 脚本
|
||||
│ ├── deploy # 部署相关脚本
|
||||
│ ├── turbo-run # Turbo 运行脚本
|
||||
│ └── vsh # VSH 脚本
|
||||
├── stylelint.config.mjs # Stylelint 配置文件
|
||||
├── turbo.json # Turbo 配置文件
|
||||
├── vben-admin.code-workspace # VS Code 工作区配置文件
|
||||
└── vitest.config.ts # Vite 配置文件
|
||||
└── vitest.config.ts # Vitest 配置文件
|
||||
```
|
||||
|
||||
@@ -5,9 +5,9 @@
|
||||
- 如果你想向项目贡献代码，请确保你的代码符合项目的代码规范。
|
||||
- 如果你使用的是 `vscode`，需要安装以下插件：
|
||||
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - 脚本代码检查
|
||||
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - 代码格式化
|
||||
- [Oxc](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) - Oxlint / Oxfmt 集成
|
||||
- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - 单词语法检查
|
||||
- [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - css 格式化
|
||||
- [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - CSS 格式检查
|
||||
|
||||
:::
|
||||
|
||||
@@ -23,59 +23,76 @@
|
||||
|
||||
## 工具
|
||||
|
||||
项目的配置文件位于 `internal/lint-configs` 下，你可以在这里修改各种lint的配置。
|
||||
项目的配置文件位于 `internal/lint-configs` 下，你可以在这里修改各种 lint 的配置。
|
||||
|
||||
项目内集成了以下几种代码校验工具：
|
||||
|
||||
- [ESLint](https://eslint.org/) 用于 JavaScript 代码检查
|
||||
- [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) 用于代码格式化
|
||||
- [Oxlint](https://oxc.rs/docs/guide/usage/linter.html) 用于 JavaScript / TypeScript 代码检查
|
||||
- [ESLint](https://eslint.org/) 用于 Vue、JSONC、YAML 等规则检查
|
||||
- [Stylelint](https://stylelint.io/) 用于 CSS 样式检查
|
||||
- [Prettier](https://prettier.io/) 用于代码格式化
|
||||
- [Commitlint](https://commitlint.js.org/) 用于检查 git 提交信息的规范
|
||||
- [Publint](https://publint.dev/) 用于检查 npm 包的规范
|
||||
- [Cspell](https://cspell.org/) 用于检查拼写错误
|
||||
- [lefthook](https://github.com/evilmartians/lefthook) 用于管理 Git hooks，在提交前自动运行代码校验和格式化
|
||||
|
||||
## ESLint
|
||||
## Oxfmt
|
||||
|
||||
ESLint 是一个代码规范和错误检查工具，用于识别和报告 TypeScript 代码中的语法错误。
|
||||
Oxfmt 用于统一项目代码风格，统一缩进、引号、尾逗号等格式。
|
||||
|
||||
### 命令
|
||||
|
||||
```bash
|
||||
pnpm eslint .
|
||||
pnpm oxfmt
|
||||
pnpm oxfmt --check
|
||||
```
|
||||
|
||||
### 配置
|
||||
|
||||
eslint 配置文件为 `eslint.config.mjs`，其核心配置放在`internal/lint-configs/eslint-config`目录下，可以根据项目需求进行修改。
|
||||
Oxfmt 的根目录入口文件为 `oxfmt.config.ts`，其核心配置位于 `internal/lint-configs/oxfmt-config` 目录下，可以根据项目需求进行修改。
|
||||
|
||||
## Oxlint
|
||||
|
||||
Oxlint 是当前仓库的主要脚本 lint 工具，用于识别和报告 JavaScript / TypeScript 代码中的问题。
|
||||
|
||||
### 命令
|
||||
|
||||
```bash
|
||||
pnpm oxlint
|
||||
pnpm oxlint --fix
|
||||
```
|
||||
|
||||
### 配置
|
||||
|
||||
Oxlint 的核心配置位于 `internal/lint-configs/oxlint-config` 目录下，根目录入口文件为 `oxlint.config.ts`。
|
||||
|
||||
## ESLint
|
||||
|
||||
ESLint 用于补充 Vue、JSONC、YAML 等规则检查。
|
||||
|
||||
### 命令
|
||||
|
||||
```bash
|
||||
pnpm eslint . --cache
|
||||
```
|
||||
|
||||
### 配置
|
||||
|
||||
ESLint 配置文件为 `eslint.config.mjs`，其核心配置放在 `internal/lint-configs/eslint-config` 目录下，可以根据项目需求进行修改。
|
||||
|
||||
## Stylelint
|
||||
|
||||
Stylelint 用于校验项目内部 css 的风格,加上编辑器的自动修复，可以很好的统一项目内部 css 风格
|
||||
Stylelint 用于校验项目内部 CSS 的风格，加上编辑器的自动修复，可以很好的统一项目内部 CSS 风格。
|
||||
|
||||
### 命令
|
||||
|
||||
```bash
|
||||
pnpm stylelint "**/*.{vue,css,less.scss}"
|
||||
pnpm stylelint "**/*.{vue,css,less,scss}" --cache
|
||||
```
|
||||
|
||||
### 配置
|
||||
|
||||
Stylelint 配置文件为 `stylelint.config.mjs`，其核心配置放在`internal/lint-configs/stylelint-config`目录下，可以根据项目需求进行修改。
|
||||
|
||||
## Prettier
|
||||
|
||||
Prettier 可以用于统一项目代码风格，统一的缩进，单双引号，尾逗号等等风格
|
||||
|
||||
### 命令
|
||||
|
||||
```bash
|
||||
pnpm prettier .
|
||||
```
|
||||
|
||||
### 配置
|
||||
|
||||
Prettier 配置文件为 `.prettier.mjs`，其核心配置放在`internal/lint-configs/prettier-config`目录下，可以根据项目需求进行修改。
|
||||
Stylelint 配置文件为 `stylelint.config.mjs`，其核心配置放在 `internal/lint-configs/stylelint-config` 目录下，可以根据项目需求进行修改。
|
||||
|
||||
## CommitLint
|
||||
|
||||
@@ -83,26 +100,26 @@ Prettier 配置文件为 `.prettier.mjs`，其核心配置放在`internal/lint-c
|
||||
|
||||
### 配置
|
||||
|
||||
CommitLint 配置文件为 `.commitlintrc.mjs`，其核心配置放在`internal/lint-configs/commitlint-config`目录下，可以根据项目需求进行修改。
|
||||
CommitLint 配置文件为 `.commitlintrc.js`，其核心配置放在 `internal/lint-configs/commitlint-config` 目录下，可以根据项目需求进行修改。
|
||||
|
||||
### Git 提交规范
|
||||
|
||||
参考 [Angular](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular)
|
||||
|
||||
- `feat` 增加新功能
|
||||
- `fix` 修复问题/BUG
|
||||
- `fix` 修复问题 / BUG
|
||||
- `style` 代码风格相关无影响运行结果的
|
||||
- `perf` 优化/性能提升
|
||||
- `perf` 优化 / 性能提升
|
||||
- `refactor` 重构
|
||||
- `revert` 撤销修改
|
||||
- `test` 测试相关
|
||||
- `docs` 文档/注释
|
||||
- `chore` 依赖更新/脚手架配置修改等
|
||||
- `docs` 文档 / 注释
|
||||
- `chore` 依赖更新 / 脚手架配置修改等
|
||||
- `workflow` 工作流改进
|
||||
- `ci` 持续集成
|
||||
- `types` 类型修改
|
||||
|
||||
### 关闭Git提交规范检查
|
||||
### 关闭 Git 提交规范检查
|
||||
|
||||
如果你想关闭 Git 提交规范检查，有两种方式：
|
||||
|
||||
@@ -112,21 +129,29 @@ CommitLint 配置文件为 `.commitlintrc.mjs`，其核心配置放在`internal/
|
||||
git commit -m 'feat: add home page' --no-verify
|
||||
```
|
||||
|
||||
```bash [永久关闭]
|
||||
# 在 .husky/commit-msg 内注释以下代码即可
|
||||
pnpm exec commitlint --edit "$1" # [!code --]
|
||||
```yaml [长期关闭]
|
||||
commit-msg:
|
||||
commands:
|
||||
# commitlint:
|
||||
# run: pnpm exec commitlint --edit $1
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
如果修改了 `lefthook.yml`，请重新执行：
|
||||
|
||||
```bash
|
||||
pnpm exec lefthook install
|
||||
```
|
||||
|
||||
## Publint
|
||||
|
||||
Publint 是一个用于检查 npm 包的规范的工具，可以检查包的版本号是否符合规范，是否符合标准的 ESM 规范包等等。
|
||||
Publint 是一个用于检查 npm 包规范的工具，可以检查包的版本号、导出方式以及 ESM 包结构等问题。
|
||||
|
||||
### 命令
|
||||
|
||||
```bash
|
||||
pnpm vsh publint
|
||||
pnpm publint
|
||||
```
|
||||
|
||||
## Cspell
|
||||
@@ -136,7 +161,7 @@ Cspell 是一个用于检查拼写错误的工具，可以检查代码中的拼
|
||||
### 命令
|
||||
|
||||
```bash
|
||||
pnpm cspell lint \"**/*.ts\" \"**/README.md\" \".changeset/*.md\" --no-progress
|
||||
pnpm check:cspell
|
||||
```
|
||||
|
||||
### 配置
|
||||
@@ -145,13 +170,13 @@ cspell 配置文件为 `cspell.json`，可以根据项目需求进行修改。
|
||||
|
||||
## Git Hook
|
||||
|
||||
git hook 一般结合各种 lint，在 git 提交代码的时候进行代码风格校验，如果校验没通过，则不会进行提交。需要开发者自行修改后再次进行提交
|
||||
git hook 一般结合各种 lint，在 git 提交代码的时候进行代码风格校验，如果校验没通过，则不会进行提交。需要开发者自行修改后再次进行提交。
|
||||
|
||||
### lefthook
|
||||
|
||||
有一个问题就是校验会校验全部代码，但是我们只想校验我们自己提交的代码，这个时候就可以使用 lefthook。
|
||||
|
||||
最有效的解决方案就是将 Lint 校验放到本地，常见做法是使用 lefthook 在本地提交之前先做一次 Lint 校验。
|
||||
最有效的解决方案就是将 lint 校验放到本地，常见做法是使用 lefthook 在本地提交之前先做一次 lint 校验。
|
||||
|
||||
项目在 `lefthook.yml` 内部定义了相应的 hooks：
|
||||
|
||||
@@ -159,52 +184,46 @@ git hook 一般结合各种 lint，在 git 提交代码的时候进行代码风
|
||||
- `code-workspace`: 更新 VSCode 工作区配置
|
||||
- `lint-md`: 格式化 Markdown 文件
|
||||
- `lint-vue`: 格式化并检查 Vue 文件
|
||||
- `lint-js`: 格式化并检查 JavaScript/TypeScript 文件
|
||||
- `lint-js`: 格式化并检查 JavaScript / TypeScript 文件
|
||||
- `lint-style`: 格式化并检查样式文件
|
||||
- `lint-package`: 格式化 package.json
|
||||
- `lint-package`: 格式化 `package.json`
|
||||
- `lint-json`: 格式化其他 JSON 文件
|
||||
|
||||
- `post-merge`: 在合并后运行，用于自动安装依赖
|
||||
- `install`: 运行 `pnpm install` 安装新依赖
|
||||
|
||||
- `commit-msg`: 在提交时运行，用于检查提交信息格式
|
||||
- `commitlint`: 使用 commitlint 检查提交信息
|
||||
|
||||
当前 hooks 可通过以下命令安装：
|
||||
|
||||
```bash
|
||||
pnpm exec lefthook install
|
||||
```
|
||||
|
||||
#### 如何关闭 lefthook
|
||||
|
||||
如果你想关闭 lefthook，有两种方式：
|
||||
如果你想临时关闭 lefthook，可以使用：
|
||||
|
||||
::: code-group
|
||||
|
||||
```bash [临时关闭]
|
||||
```bash
|
||||
git commit -m 'feat: add home page' --no-verify
|
||||
```
|
||||
|
||||
```bash [永久关闭]
|
||||
# 删除 lefthook.yml 文件即可
|
||||
rm lefthook.yml
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
#### 如何修改 lefthook 配置
|
||||
|
||||
如果你想修改 lefthook 的配置，可以编辑 `lefthook.yml` 文件。例如：
|
||||
|
||||
```yaml
|
||||
pre-commit:
|
||||
parallel: true # 并行执行任务
|
||||
jobs:
|
||||
- name: lint-js
|
||||
run: pnpm prettier --cache --ignore-unknown --write {staged_files}
|
||||
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`: 是否并行执行任务
|
||||
- `jobs`: 定义要执行的任务列表
|
||||
- `name`: 任务名称
|
||||
- `commands`: 定义要执行的任务列表
|
||||
- `run`: 要执行的命令
|
||||
- `glob`: 匹配的文件模式
|
||||
- `{staged_files}`: 表示暂存的文件列表
|
||||
|
||||
@@ -1,17 +1,38 @@
|
||||
# Tailwind CSS
|
||||
|
||||
[Tailwind CSS](https://tailwindcss.com/) 是一个实用性优先的CSS框架，用于快速构建自定义设计。
|
||||
[Tailwind CSS](https://tailwindcss.com/) 是一个实用性优先的 CSS 框架，用于快速构建自定义设计。当前项目使用的是 **Tailwind CSS v4**。
|
||||
|
||||
## 配置
|
||||
|
||||
项目的配置文件位于 `internal/tailwind-config` 下，你可以在这里修改 Tailwind CSS 的配置。
|
||||
项目当前不再通过 `tailwind.config.*` 文件维护 Tailwind 配置，主题与扫描范围都统一放在 CSS 与共享 Vite 配置中。
|
||||
|
||||
::: tip 包使用 tailwindcss 的限制
|
||||
- 主题入口：`packages/@core/base/design/src/css/global.css`
|
||||
- Vite 集成：`internal/vite-config`
|
||||
|
||||
当前只有对应的包下面存在 `tailwind.config.mjs` 文件才会启用 tailwindcss 的编译，否则不会启用 tailwindcss。如果你是纯粹的 SDK 包，不需要使用 tailwindcss，可以不用创建 `tailwind.config.mjs` 文件。
|
||||
在 `global.css` 中你会看到当前项目使用的 Tailwind CSS v4 指令，例如：
|
||||
|
||||
- `@source`
|
||||
- `@custom-variant`
|
||||
- `@theme`
|
||||
- `@theme inline`
|
||||
- `@utility`
|
||||
|
||||
## 包使用 Tailwind CSS 的方式
|
||||
|
||||
当前项目不会根据某个包下是否存在 `tailwind.config.mjs` 来决定是否启用 Tailwind CSS。
|
||||
|
||||
应用和包统一复用 `@vben/vite-config`，并由该配置接入 `@tailwindcss/vite`。Tailwind 的扫描范围则统一在 `packages/@core/base/design/src/css/global.css` 中维护。
|
||||
|
||||
::: tip 包使用 Tailwind CSS 的说明
|
||||
|
||||
如果你是纯粹的 SDK 包，不需要使用 Tailwind CSS，则无需额外增加旧版 `tailwind.config.*` 文件。
|
||||
|
||||
:::
|
||||
|
||||
## 提示
|
||||
## Vue SFC 中的 `@apply`
|
||||
|
||||
现`tailwindcss`已至v4.x版本，使用方法与`tailwindcss: ^3.4.17`有差异，v4.0无法与v3.x版本兼容，在开发前请确认`package.json`中的`tailwindcss`版本。
|
||||
项目对 Vue 单文件组件中的 `@apply` 做了统一处理，相关逻辑位于：
|
||||
|
||||
- `internal/vite-config/src/plugins/tailwind-reference.ts`
|
||||
|
||||
当组件样式中使用 `@apply` 时，会自动注入对应的 `@reference`，一般不需要手动补充。
|
||||
|
||||
Reference in New Issue
Block a user