tsai
/
vue-vben-admin
mirror of https://github.com/vbenjs/vue-vben-admin
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

docs(@vben/docs): align guide docs with current tooling

pull/7655/head
xingyu4j 1 week ago
parent
278032c94b
commit
6c274b75b8
11 changed files with 388 additions and 256 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 42
      docs/src/en/guide/essentials/development.md
  2. 6
      docs/src/en/guide/introduction/vben.md
  3. 98
      docs/src/en/guide/project/dir.md
  4. 121
      docs/src/en/guide/project/standard.md
  5. 33
      docs/src/en/guide/project/tailwindcss.md
  6. 84
      docs/src/guide/essentials/development.md
  7. 6
      docs/src/guide/introduction/vben.md
  8. 2
      docs/src/guide/introduction/why.md
  9. 96
      docs/src/guide/project/dir.md
  10. 123
      docs/src/guide/project/standard.md
  11. 33
      docs/src/guide/project/tailwindcss.md

42
docs/src/en/guide/essentials/development.md
View File

@ -32,14 +32,14 @@ If you are using [vscode](https://code.visualstudio.com/) (recommended) as your
- [Iconify IntelliSense](https://marketplace.visualstudio.com/items?itemName=antfu.iconify) - Iconify icon plugin. - [Iconify IntelliSense](https://marketplace.visualstudio.com/items?itemName=antfu.iconify) - Iconify icon plugin.
- [i18n Ally](https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally) - i18n plugin. - [i18n Ally](https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally) - i18n plugin.
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - Script code linting. - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - Script code linting.
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - Code formatting. - [Oxc](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) - Oxlint / Oxfmt integration.
- [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - CSS formatting. - [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - CSS formatting.
- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - Spelling checker. - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - Spelling checker.
- [DotENV](https://marketplace.visualstudio.com/items?itemName=mikestead.dotenv) - .env file highlighting. - [DotENV](https://marketplace.visualstudio.com/items?itemName=mikestead.dotenv) - .env file highlighting.
## Npm Scripts ## Npm Scripts
Npm scripts are common configurations used in the project to perform common tasks such as starting the project, building the project, etc. The following scripts can be found in the `package.json` file at the root of the project. Npm scripts are common configurations used in the project to perform common tasks such as starting the project, building the project, and more. The following scripts can be found in the `package.json` file at the root of the project.
The execution command is: `pnpm run [script]` or `npm run [script]`. The execution command is: `pnpm run [script]` or `npm run [script]`.
@ -51,15 +51,17 @@ The execution command is: `pnpm run [script]` or `npm run [script]`.
// Build the project with analysis // Build the project with analysis
"build:analyze": "turbo build:analyze", "build:analyze": "turbo build:analyze",
// Build a local Docker image // Build a local Docker image
"build:docker": "./build-local-docker-image.sh", "build:docker": "./scripts/deploy/build-local-docker-image.sh",
// Build the web-antd application separately // Build the web-antd application separately
"build:antd": "pnpm run build --filter=@vben/web-antd", "build:antd": "pnpm run build --filter=@vben/web-antd",
// Build the web-antdv-next application separately
"build:antdv-next": "pnpm run build --filter=@vben/web-antdv-next",
// Build the documentation separately // Build the documentation separately
"build:docs": "pnpm run build --filter=@vben/docs", "build:docs": "pnpm run build --filter=@vben/docs",
// Build the web-ele application separately // Build the web-ele application separately
"build:ele": "pnpm run build --filter=@vben/web-ele", "build:ele": "pnpm run build --filter=@vben/web-ele",
// Build the web-naive application separately // Build the web-naive application separately
"build:naive": "pnpm run build --filter=@vben/naive", "build:naive": "pnpm run build --filter=@vben/web-naive",
// Build the web-tdesign application separately // Build the web-tdesign application separately
"build:tdesign": "pnpm run build --filter=@vben/web-tdesign", "build:tdesign": "pnpm run build --filter=@vben/web-tdesign",
// Build the playground application separately // Build the playground application separately
@ -71,7 +73,7 @@ The execution command is: `pnpm run [script]` or `npm run [script]`.
// Check for circular dependencies // Check for circular dependencies
"check:circular": "vsh check-circular", "check:circular": "vsh check-circular",
// Check spelling // Check spelling
"check:cspell": "cspell lint **/*.ts **/README.md .changeset/*.md --no-progress" "check:cspell": "cspell lint **/*.ts **/README.md .changeset/*.md --no-progress",
// Check dependencies // Check dependencies
"check:dep": "vsh check-dep", "check:dep": "vsh check-dep",
// Check types // Check types
@ -84,12 +86,16 @@ The execution command is: `pnpm run [script]` or `npm run [script]`.
"dev": "turbo-run dev", "dev": "turbo-run dev",
// Start the web-antd application // Start the web-antd application
"dev:antd": "pnpm -F @vben/web-antd run dev", "dev:antd": "pnpm -F @vben/web-antd run dev",
// Start the web-antdv-next application
"dev:antdv-next": "pnpm -F @vben/web-antdv-next run dev",
// Start the documentation // Start the documentation
"dev:docs": "pnpm -F @vben/docs run dev", "dev:docs": "pnpm -F @vben/docs run dev",
// Start the web-ele application // Start the web-ele application
"dev:ele": "pnpm -F @vben/web-ele run dev", "dev:ele": "pnpm -F @vben/web-ele run dev",
// Start the web-naive application // Start the web-naive application
"dev:naive": "pnpm -F @vben/web-naive run dev", "dev:naive": "pnpm -F @vben/web-naive run dev",
// Start the web-tdesign application
"dev:tdesign": "pnpm -F @vben/web-tdesign run dev",
// Start the playground application // Start the playground application
"dev:play": "pnpm -F @vben/playground run dev", "dev:play": "pnpm -F @vben/playground run dev",
// Format code // Format code
@ -101,17 +107,19 @@ The execution command is: `pnpm run [script]` or `npm run [script]`.
// Only allow using pnpm // Only allow using pnpm
"preinstall": "npx only-allow pnpm", "preinstall": "npx only-allow pnpm",
// Install lefthook // Install lefthook
"prepare": "is-ci || lefthook install", "prepare": "pnpm exec lefthook install",
// Preview the application // Preview the application
"preview": "turbo-run preview", "preview": "turbo-run preview",
// Package specification check // Package specification check
"publint": "vsh publint", "publint": "vsh publint",
// Delete all node_modules, yarn.lock, package.lock.json, and reinstall dependencies // Delete all node_modules, yarn.lock, package-lock.json, and reinstall dependencies
"reinstall": "pnpm clean --del-lock && pnpm install", "reinstall": "pnpm clean --del-lock && pnpm install",
// Run e2e tests
"test:e2e": "turbo run test:e2e",
// Run vitest unit tests // Run vitest unit tests
"test:unit": "vitest run --dom", "test:unit": "vitest run --dom",
// Update project dependencies // Update project dependencies
"update:deps": " pnpm update --latest --recursive", "update:deps": "npx taze -r -w",
// Changeset generation and versioning // Changeset generation and versioning
"version": "pnpm exec changeset version && pnpm install --no-frozen-lockfile" "version": "pnpm exec changeset version && pnpm install --no-frozen-lockfile"
} }
@ -134,6 +142,12 @@ To run the `web-antd` application:
pnpm dev:antd pnpm dev:antd
``` ```
To run the `web-antdv-next` application:
```bash
pnpm dev:antdv-next
```
To run the `web-naive` application: To run the `web-naive` application:
```bash ```bash
@ -146,6 +160,12 @@ To run the `web-ele` application:
pnpm dev:ele pnpm dev:ele
``` ```
To run the `web-tdesign` application:
```bash
pnpm dev:tdesign
```
To run the `docs` application: To run the `docs` application:
```bash ```bash
@ -221,9 +241,9 @@ Add the relevant dependent commands in `turbo.json`.
## Public Static Resources ## Public Static Resources
If you need to use public static resources in the project, such as images, static HTML, etc., and you want to directly import them in the development process through `src="/xxx.png"`. If you need to use public static resources in the project, such as images and static HTML, and want to import them directly during development through `src="/xxx.png"`.
You need to put the resource in the corresponding project's `public/static` directory. The import path for the resource should be `src="/static/xxx.png"`. You need to put the resources in the `public/static` directory of the corresponding project. The import path for the resources should be `src="/static/xxx.png"`.
## DevTools ## DevTools
@ -251,7 +271,7 @@ If you encounter dependency-related issues, you can try reinstalling the depende
```bash ```bash
# Execute this command at the root of the project. # Execute this command at the root of the project.
# This command will delete all node_modules, yarn.lock, and package.lock.json files # This command will delete all node_modules, yarn.lock, and package-lock.json files
# and then reinstall dependencies (this process will be noticeably slower). # and then reinstall dependencies (this process will be noticeably slower).
pnpm reinstall pnpm reinstall
``` ```

6
docs/src/en/guide/introduction/vben.md
View File

@ -20,9 +20,9 @@
- **Dynamic Menu**: Supports dynamic menus that can display based on permissions. - **Dynamic Menu**: Supports dynamic menus that can display based on permissions.
- **Mock Data**: High-performance local Mock data solution based on `Nitro`. - **Mock Data**: High-performance local Mock data solution based on `Nitro`.
- **Rich Components**: Provides a wide range of components to meet most business needs. - **Rich Components**: Provides a wide range of components to meet most business needs.
- **Standardization**: Code quality is ensured with tools like `ESLint`, `Prettier`, `Stylelint`, `Publint`, and `CSpell`. - **Standardization**: Code quality is ensured with tools like `Oxfmt`, `Oxlint`, `ESLint`, `Stylelint`, `Publint`, and `CSpell`.
- **Engineering**: Development efficiency is improved with tools like `Pnpm Monorepo`, `TurboRepo`, and `Changeset`. - **Engineering**: Development efficiency is improved with tools like `Pnpm Monorepo`, `Turborepo`, and `Changeset`.
- **Multi-UI Library Support**: Supports mainstream UI libraries like `Ant Design Vue`, `Element Plus`, and `Vuetify`, without being restricted to a specific framework. - **Multi-UI Library Support**: Supports mainstream UI libraries like `Ant Design Vue`, `Ant Design Vue Next`, `Element Plus`, `Naive UI`, and `TDesign`, without being restricted to a specific framework.
## Browser Support ## Browser Support

98
docs/src/en/guide/project/dir.md
View File

@ -1,68 +1,72 @@
# Directory Explanation # Directory Explanation
The directory uses Monorepo management, and the project structure is as follows: The repository uses Monorepo management, and the project structure is as follows:
```bash ```bash
. .
├── Dockerfile # Docker image build file
├── README.md # Project documentation ├── README.md # Project documentation
├── apps # Project applications directory ├── apps # Project applications directory
│   ├── backend-mock # Backend mock service application │ ├── backend-mock # Backend mock service application
│   ├── web-antd # Frontend application based on Ant Design Vue │ ├── web-antd # Frontend application based on Ant Design Vue
│   ├── web-ele # Frontend application based on Element Plus │ ├── web-antdv-next # Frontend application based on Ant Design Vue Next
│   └── web-naive # Frontend application based on Naive UI │ ├── web-ele # Frontend application based on Element Plus
├── build-local-docker-image.sh # Script for building Docker images locally │ ├── web-naive # Frontend application based on Naive UI
│ └── web-tdesign # Frontend application based on TDesign
├── cspell.json # CSpell configuration file ├── cspell.json # CSpell configuration file
├── docs # Project documentation directory ├── docs # Project documentation directory
├── eslint.config.mjs # ESLint configuration file ├── eslint.config.mjs # ESLint configuration file
├── lefthook.yml # Git hook configuration file
├── internal # Internal tools directory ├── internal # Internal tools directory
│   ├── lint-configs # Code linting configurations │ ├── lint-configs # Code linting configurations
│   │   ├── commitlint-config # Commitlint configuration │ │ ├── commitlint-config # Commitlint configuration
│   │   ├── eslint-config # ESLint configuration │ │ ├── eslint-config # ESLint configuration
│   │   ├── prettier-config # Prettier configuration │ │ ├── oxfmt-config # Oxfmt configuration
│   │   └── stylelint-config # Stylelint configuration │ │ ├── oxlint-config # Oxlint configuration
│   ├── node-utils # Node.js tools │ │ └── stylelint-config # Stylelint configuration
│   ├── tailwind-config # Tailwind configuration │ ├── node-utils # Node.js tools
│   ├── tsconfig # Common tsconfig settings │ ├── tsconfig # Common tsconfig settings
│   └── vite-config # Common Vite configuration │ └── vite-config # Common Vite configuration
├── oxfmt.config.ts # Oxfmt config entry
├── oxlint.config.ts # Oxlint configuration file
├── package.json # Project dependency configuration ├── package.json # Project dependency configuration
├── packages # Project packages directory ├── packages # Project packages directory
│   ├── @core # Core package │ ├── @core # Core package
│   │   ├── base # Base package │ │ ├── base # Base package
│   │   │   ├── design # Design related │ │ │ ├── design # Design related
│   │   │   ├── icons # Icons │ │ │ ├── icons # Icons
│   │   │   ├── shared # Shared │ │ │ ├── shared # Shared
│   │   │   └── typings # Type definitions │ │ │ └── typings # Type definitions
│   │   ├── composables # Composable APIs │ │ ├── composables # Composable APIs
│   │   ├── preferences # Preferences │ │ ├── preferences # Preferences
│   │   └── ui-kit # UI component collection │ │ └── ui-kit # UI component collection
│   │   ├── layout-ui # Layout UI │ │ ├── layout-ui # Layout UI
│   │   ├── menu-ui # Menu UI │ │ ├── menu-ui # Menu UI
│   │   ├── shadcn-ui # shadcn UI │ │ ├── shadcn-ui # shadcn UI
│   │   └── tabs-ui # Tabs UI │ │ └── tabs-ui # Tabs UI
│   ├── constants # Constants │ ├── constants # Constants
│   ├── effects # Effects related packages │ ├── effects # Effects related packages
│   │   ├── access # Access control │ │ ├── access # Access control
│   │   ├── plugins # Plugins │ │ ├── plugins # Large third-party dependency plugins
│   │   ├── common-ui # Common UI │ │ ├── common-ui # Common UI
│   │   ├── hooks # Composable APIs │ │ ├── hooks # Composable APIs
│   │   ├── layouts # Layouts │ │ ├── layouts # Layouts
│   │   └── request # Request │ │ └── request # Request
│   ├── icons # Icons │ ├── icons # Icons
│   ├── locales # Internationalization │ ├── locales # Internationalization
│   ├── preferences # Preferences │ ├── preferences # Preferences
│   ├── stores # State management │ ├── stores # State management
│   ├── styles # Styles │ ├── styles # Styles
│   ├── types # Type definitions │ ├── types # Type definitions
│   └── utils # Utilities │ └── utils # Utilities
├── playground # Demo directory ├── playground # Demo directory
├── pnpm-lock.yaml # pnpm lock file ├── pnpm-lock.yaml # pnpm lock file
├── pnpm-workspace.yaml # pnpm workspace configuration file ├── pnpm-workspace.yaml # pnpm workspace configuration file
├── scripts # Scripts directory ├── scripts # Scripts directory
│   ├── turbo-run # Turbo run script │ ├── deploy # Deployment-related scripts
│   └── vsh # VSH script │ ├── turbo-run # Turbo run script
│ └── vsh # VSH script
├── stylelint.config.mjs # Stylelint configuration file ├── stylelint.config.mjs # Stylelint configuration file
├── turbo.json # Turbo configuration file ├── turbo.json # Turbo configuration file
├── vben-admin.code-workspace # VS Code workspace configuration file ├── vben-admin.code-workspace # VS Code workspace configuration file
└── vitest.config.ts # Vite configuration file └── vitest.config.ts # Vitest configuration file
``` ```

121
docs/src/en/guide/project/standard.md
View File

@ -5,7 +5,7 @@
- If you want to contribute code to the project, please ensure your code complies with the project's coding standards. - If you want to contribute code to the project, please ensure your code complies with the project's coding standards.
- If you are using `vscode`, you need to install the following plugins: - If you are using `vscode`, you need to install the following plugins:
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - Script code checking - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - Script code checking
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - Code formatting - [Oxc](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) - Oxlint / Oxfmt integration
- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - Word syntax checking - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - Word syntax checking
- [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - CSS formatting - [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - CSS formatting
@ -27,77 +27,94 @@ The project's configuration files are located in `internal/lint-configs`, where
The project integrates the following code verification tools: The project integrates the following code verification tools:
- [ESLint](https://eslint.org/) for JavaScript code checking - [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) for code formatting
- [Oxlint](https://oxc.rs/docs/guide/usage/linter.html) for JavaScript / TypeScript linting
- [ESLint](https://eslint.org/) for Vue, JSONC, YAML, and related rules
- [Stylelint](https://stylelint.io/) for CSS style checking - [Stylelint](https://stylelint.io/) for CSS style checking
- [Prettier](https://prettier.io/) for code formatting
- [Commitlint](https://commitlint.js.org/) for checking the standard of git commit messages - [Commitlint](https://commitlint.js.org/) for checking the standard of git commit messages
- [Publint](https://publint.dev/) for checking the standard of npm packages - [Publint](https://publint.dev/) for checking the standard of npm packages
- [Cspell](https://cspell.org/) for checking spelling errors - [Cspell](https://cspell.org/) for checking spelling errors
- [lefthook](https://github.com/evilmartians/lefthook) for managing Git hooks, automatically running code checks and formatting before commits - [lefthook](https://github.com/evilmartians/lefthook) for managing Git hooks, automatically running code checks and formatting before commits
## ESLint ## Oxfmt
ESLint is a code standard and error checking tool used to identify and report syntax errors in TypeScript code. Oxfmt is used to keep code formatting consistent across the repository.
### Command ### Command
```bash ```bash
pnpm eslint . pnpm oxfmt
pnpm oxfmt --check
``` ```
### Configuration ### Configuration
The ESLint configuration file is `eslint.config.mjs`, with its core configuration located in the `internal/lint-configs/eslint-config` directory, which can be modified according to project needs. The root Oxfmt entry file is `oxfmt.config.ts`, and its core configuration is located in `internal/lint-configs/oxfmt-config`.
## Stylelint ## Oxlint
Stylelint is used to check the style of CSS within the project. Coupled with the editor's auto-fix feature, it can effectively unify the CSS style within the project. Oxlint is the primary script linting tool for the repository.
### Command ### Command
```bash ```bash
pnpm stylelint "**/*.{vue,css,less.scss}" pnpm oxlint
pnpm oxlint --fix
``` ```
### Configuration ### Configuration
The Stylelint configuration file is `stylelint.config.mjs`, with its core configuration located in the `internal/lint-configs/stylelint-config` directory, which can be modified according to project needs. The core Oxlint configuration is located in `internal/lint-configs/oxlint-config`, and the root entry file is `oxlint.config.ts`.
## Prettier ## ESLint
ESLint is used to complement Vue, JSONC, YAML, and related rules.
Prettier Can be used to unify project code style, consistent indentation, single and double quotes, trailing commas, and other styles. ### Command
```bash
pnpm eslint . --cache
```
### Configuration
The ESLint configuration file is `eslint.config.mjs`, with its core configuration located in the `internal/lint-configs/eslint-config` directory, which can be modified according to project needs.
## Stylelint
Stylelint is used to check the style of CSS within the project. Coupled with the editor's auto-fix feature, it can effectively unify the CSS style within the project.
### Command ### Command
```bash ```bash
pnpm prettier . pnpm stylelint "**/*.{vue,css,less,scss}" --cache
``` ```
### Configuration ### Configuration
The Prettier configuration file is `.prettier.mjs`, with its core configuration located in the `internal/lint-configs/prettier-config` directory, which can be modified according to project needs. The Stylelint configuration file is `stylelint.config.mjs`, with its core configuration located in the `internal/lint-configs/stylelint-config` directory, which can be modified according to project needs.
## CommitLint ## CommitLint
In a team, everyone's git commit messages can vary widely, making it difficult to ensure standardization without a mechanism. How can standardization be achieved? You might think of using git's hook mechanism to write shell scripts to implement this. Of course, this is possible, but actually, JavaScript has a great tool for implementing this template, which is commitlint (used for verifying the standard of git commit messages). In a team, everyone's git commit messages can vary widely, making it difficult to ensure standardization without a mechanism. You might think of using git's hook mechanism to write shell scripts to implement this. Of course, this is possible, but JavaScript has a good tool for this template: commitlint.
### Configuration ### Configuration
The CommitLint configuration file is `.commitlintrc.mjs`, with its core configuration located in the `internal/lint-configs/commitlint-config` directory, which can be modified according to project needs. The CommitLint configuration file is `.commitlintrc.js`, with its core configuration located in the `internal/lint-configs/commitlint-config` directory, which can be modified according to project needs.
### Git Commit Standards ### Git Commit Standards
Refer to [Angular](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular) Refer to [Angular](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular)
- `feat` Add new features - `feat` Add new features
- `fix` Fix problems/BUGs - `fix` Fix problems / BUGs
- `style` Code style changes that do not affect the outcome - `style` Code style changes that do not affect the outcome
- `perf` Optimization/performance improvement - `perf` Optimization / performance improvement
- `refactor` Refactoring - `refactor` Refactoring
- `revert` Revert changes - `revert` Revert changes
- `test` Related to tests - `test` Related to tests
- `docs` Documentation/comments - `docs` Documentation / comments
- `chore` Dependency updates/scaffold configuration modifications, etc. - `chore` Dependency updates / scaffold configuration changes
- `workflow` Workflow improvements - `workflow` Workflow improvements
- `ci` Continuous integration - `ci` Continuous integration
- `types` Type modifications - `types` Type modifications
@ -112,31 +129,39 @@ If you want to disable Git commit standard checks, there are two ways:
git commit -m 'feat: add home page' --no-verify git commit -m 'feat: add home page' --no-verify
``` ```
```bash [Permanent closed] ```yaml [Long-term disable]
# Comment out the following code in .husky/commit-msg to disable commit-msg:
pnpm exec commitlint --edit "$1" # [!code --] commands:
# commitlint:
# run: pnpm exec commitlint --edit $1
``` ```
::: :::
If you changed `lefthook.yml`, reinstall hooks with:
```bash
pnpm exec lefthook install
```
## Publint ## Publint
Publint is a tool for checking the standard of npm packages, which can check whether the package version conforms to the standard, whether it conforms to the standard ESM package specification, etc. Publint is a tool for checking npm package standards, including package versioning, exports, and ESM package structure.
### Command ### Command
```bash ```bash
pnpm vsh publint pnpm publint
``` ```
## Cspell ## Cspell
Cspell is a tool for checking spelling errors, which can check for spelling errors in the code, avoiding bugs caused by spelling errors. Cspell is a tool for checking spelling errors in the code, avoiding bugs caused by spelling mistakes.
### Command ### Command
```bash ```bash
pnpm cspell lint \"**/*.ts\" \"**/README.md\" \".changeset/*.md\" --no-progress pnpm check:cspell
``` ```
### Configuration ### Configuration
@ -149,9 +174,9 @@ Git hooks are generally combined with various lints to check code style during g
### lefthook ### lefthook
One issue is that the check will verify all code, but we only want to check the code we are committing. This is where lefthook comes in. One issue is that the check would verify all code, but in practice we usually only want to check the code being committed. This is where lefthook comes in.
The most effective solution is to perform Lint checks locally before committing. A common practice is to use lefthook to perform a Lint check before local submission. The most effective solution is to perform lint checks locally before committing. A common practice is to use lefthook to perform checks before local submission.
The project defines corresponding hooks inside `lefthook.yml`: The project defines corresponding hooks inside `lefthook.yml`:
@ -159,52 +184,46 @@ The project defines corresponding hooks inside `lefthook.yml`:
- `code-workspace`: Updates VSCode workspace configuration - `code-workspace`: Updates VSCode workspace configuration
- `lint-md`: Formats Markdown files - `lint-md`: Formats Markdown files
- `lint-vue`: Formats and checks Vue files - `lint-vue`: Formats and checks Vue files
- `lint-js`: Formats and checks JavaScript/TypeScript files - `lint-js`: Formats and checks JavaScript / TypeScript files
- `lint-style`: Formats and checks style files - `lint-style`: Formats and checks style files
- `lint-package`: Formats package.json - `lint-package`: Formats `package.json`
- `lint-json`: Formats other JSON files - `lint-json`: Formats other JSON files
- `post-merge`: Runs after merge, used for automatic dependency installation - `post-merge`: Runs after merge, used for automatic dependency installation
- `install`: Runs `pnpm install` to install new dependencies - `install`: Runs `pnpm install` to install new dependencies
- `commit-msg`: Runs during commit, used for checking commit message format - `commit-msg`: Runs during commit, used for checking commit message format
- `commitlint`: Uses commitlint to check commit messages - `commitlint`: Uses commitlint to check commit messages
#### How to Disable lefthook Current hooks can be installed with:
If you want to disable lefthook, there are two ways: ```bash
pnpm exec lefthook install
```
::: code-group #### How to Disable lefthook
```bash [Temporary disable] If you want to temporarily disable lefthook, use:
git commit -m 'feat: add home page' --no-verify
```
```bash [Permanent disable] ```bash
# Simply delete the lefthook.yml file git commit -m 'feat: add home page' --no-verify
rm lefthook.yml
``` ```
:::
#### How to Modify lefthook Configuration #### How to Modify lefthook Configuration
If you want to modify lefthook's configuration, you can edit the `lefthook.yml` file. For example: If you want to modify lefthook's configuration, you can edit the `lefthook.yml` file. For example:
```yaml ```yaml
pre-commit: pre-commit:
parallel: true # Execute tasks in parallel parallel: true
jobs: commands:
- name: lint-js lint-js:
run: pnpm prettier --cache --ignore-unknown --write {staged_files} run: pnpm oxfmt {staged_files} && pnpm oxlint --fix {staged_files} && pnpm eslint --cache --fix {staged_files}
glob: '*.{js,jsx,ts,tsx}' glob: '*.{js,jsx,ts,tsx}'
``` ```
Where: Where:
- `parallel`: Whether to execute tasks in parallel - `parallel`: Whether to execute tasks in parallel
- `jobs`: Defines the list of tasks to execute - `commands`: Defines the list of tasks to execute
- `name`: Task name
- `run`: Command to execute - `run`: Command to execute
- `glob`: File pattern to match - `glob`: File pattern to match
- `{staged_files}`: Represents the list of staged files - `{staged_files}`: Represents the list of staged files

33
docs/src/en/guide/project/tailwindcss.md
View File

@ -1,13 +1,38 @@
# Tailwind CSS # Tailwind CSS
[Tailwind CSS](https://tailwindcss.com/) is a utility-first CSS framework for quickly building custom designs. [Tailwind CSS](https://tailwindcss.com/) is a utility-first CSS framework for quickly building custom designs. The current project uses **Tailwind CSS v4**.
## Configuration ## Configuration
The project's configuration file is located in `internal/tailwind-config`, where you can modify the Tailwind CSS configuration. The project no longer maintains Tailwind through `tailwind.config.*` files. Theme definitions and scan scope are now managed through CSS and the shared Vite configuration.
::: tip Restrictions on using tailwindcss in packages - Theme entry: `packages/@core/base/design/src/css/global.css`
- Vite integration: `internal/vite-config`
Tailwind CSS compilation will only be enabled if there is a `tailwind.config.mjs` file present in the corresponding package. Otherwise, Tailwind CSS will not be enabled. If you have a pure SDK package that does not require Tailwind CSS, you do not need to create a `tailwind.config.mjs` file. In `global.css`, you will see the Tailwind CSS v4 directives currently used by the project, such as:
- `@source`
- `@custom-variant`
- `@theme`
- `@theme inline`
- `@utility`
## How Packages Use Tailwind CSS
The project does not decide whether Tailwind CSS is enabled based on whether a package contains `tailwind.config.mjs`.
Apps and packages share `@vben/vite-config`, which integrates `@tailwindcss/vite`. The Tailwind scan scope is managed centrally in `packages/@core/base/design/src/css/global.css`.
::: tip Notes on using Tailwind CSS in packages
If you are building a pure SDK package and do not need Tailwind CSS, you do not need to add any legacy `tailwind.config.*` file.
::: :::
## `@apply` in Vue SFCs
The project applies a shared handling layer for `@apply` inside Vue single-file components. The related logic is located at:
- `internal/vite-config/src/plugins/tailwind-reference.ts`
When component styles use `@apply`, the required `@reference` is injected automatically in most cases.

84
docs/src/guide/essentials/development.md
View File

@ -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 官方插件（必备）。 - [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) - Vue 官方插件（必备）。
- [Tailwind CSS](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) - Tailwindcss 提示插件。 - [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 变量提示插件。 - [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 图标插件 - [Iconify IntelliSense](https://marketplace.visualstudio.com/items?itemName=antfu.iconify) - Iconify 图标插件。
- [i18n Ally](https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally) - i18n 插件 - [i18n Ally](https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally) - i18n 插件。
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - 脚本代码检查 - [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 集成。
- [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - css 格式化 - [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - CSS 格式检查。
- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - 单词语法检查 - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - 单词语法检查。
- [DotENV](https://marketplace.visualstudio.com/items?itemName=mikestead.dotenv) - .env 文件 高亮 - [DotENV](https://marketplace.visualstudio.com/items?itemName=mikestead.dotenv) - `.env` 文件高亮。
## Npm Scripts ## Npm Scripts
@ -51,15 +51,17 @@ npm 脚本是项目常见的配置，用于执行一些常见的任务，比如
// 构建项目并分析 // 构建项目并分析
"build:analyze": "turbo build:analyze", "build:analyze": "turbo build:analyze",
// 构建本地 docker 镜像 // 构建本地 docker 镜像
"build:docker": "./build-local-docker-image.sh", "build:docker": "./scripts/deploy/build-local-docker-image.sh",
// 单独构建 web-antd 应用 // 单独构建 web-antd 应用
"build:antd": "pnpm run build --filter=@vben/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", "build:docs": "pnpm run build --filter=@vben/docs",
// 单独构建 web-ele 应用 // 单独构建 web-ele 应用
"build:ele": "pnpm run build --filter=@vben/web-ele", "build:ele": "pnpm run build --filter=@vben/web-ele",
// 单独构建 web-naive 应用 // 单独构建 web-naive 应用
"build:naive": "pnpm run build --filter=@vben/naive", "build:naive": "pnpm run build --filter=@vben/web-naive",
// 单独构建 web-tdesign 应用 // 单独构建 web-tdesign 应用
"build:tdesign": "pnpm run build --filter=@vben/web-tdesign", "build:tdesign": "pnpm run build --filter=@vben/web-tdesign",
// 单独构建 playground 应用 // 单独构建 playground 应用
@ -71,48 +73,54 @@ npm 脚本是项目常见的配置，用于执行一些常见的任务，比如
// 检查循环引用 // 检查循环引用
"check:circular": "vsh check-circular", "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:dep": "vsh check-dep",
// 检查类型 // 检查类型
"check:type": "turbo run typecheck", "check:type": "turbo run typecheck",
// 清理项目（删除node_modules、dist、.turbo）等目录 // 清理项目（删除 node_modules、dist、.turbo）等目录
"clean": "node ./scripts/clean.mjs", "clean": "node ./scripts/clean.mjs",
// 提交代码 // 提交代码
"commit": "czg", "commit": "czg",
// 启动项目（默认会运行整个仓库所有包的dev脚本） // 启动项目（默认会运行整个仓库所有包的 dev 脚本）
"dev": "turbo-run dev", "dev": "turbo-run dev",
// 启动web-antd应用 // 启动 web-antd 应用
"dev:antd": "pnpm -F @vben/web-antd run dev", "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", "dev:docs": "pnpm -F @vben/docs run dev",
// 启动web-ele应用 // 启动 web-ele 应用
"dev:ele": "pnpm -F @vben/web-ele run dev", "dev:ele": "pnpm -F @vben/web-ele run dev",
// 启动web-naive应用 // 启动 web-naive 应用
"dev:naive": "pnpm -F @vben/web-naive run dev", "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", "dev:play": "pnpm -F @vben/playground run dev",
// 格式化代码 // 格式化代码
"format": "vsh lint --format", "format": "vsh lint --format",
// lint 代码 // lint 代码
"lint": "vsh lint", "lint": "vsh lint",
// 依赖安装完成之后，执行所有包的stub脚本 // 依赖安装完成之后，执行所有包的 stub 脚本
"postinstall": "pnpm -r run stub --if-present", "postinstall": "pnpm -r run stub --if-present",
// 只允许使用pnpm // 只允许使用 pnpm
"preinstall": "npx only-allow pnpm", "preinstall": "npx only-allow pnpm",
// lefthook的安装 // 安装 lefthook
"prepare": "is-ci || lefthook install", "prepare": "pnpm exec lefthook install",
// 预览应用 // 预览应用
"preview": "turbo-run preview", "preview": "turbo-run preview",
// 包规范检查 // 包规范检查
"publint": "vsh publint", "publint": "vsh publint",
// 删除所有的node_modules、yarn.lock、package.lock.json，重新安装依赖 // 删除所有的 node_modules、yarn.lock、package-lock.json，重新安装依赖
"reinstall": "pnpm clean --del-lock && pnpm install", "reinstall": "pnpm clean --del-lock && pnpm install",
// 运行 e2e 测试
"test:e2e": "turbo run test:e2e",
// 运行 vitest 单元测试 // 运行 vitest 单元测试
"test:unit": "vitest run --dom", "test:unit": "vitest run --dom",
// 更新项目依赖 // 更新项目依赖
"update:deps": " pnpm update --latest --recursive", "update:deps": "npx taze -r -w",
// changeset生成提交集 // changeset 生成提交集
"version": "pnpm exec changeset version && pnpm install --no-frozen-lockfile" "version": "pnpm exec changeset version && pnpm install --no-frozen-lockfile"
} }
} }
@ -134,6 +142,12 @@ pnpm dev
pnpm dev:antd pnpm dev:antd
``` ```
运行 `web-antdv-next` 应用：
```bash
pnpm dev:antdv-next
```
运行 `web-naive` 应用： 运行 `web-naive` 应用：
```bash ```bash
@ -146,6 +160,12 @@ pnpm dev:naive
pnpm dev:ele pnpm dev:ele
``` ```
运行 `web-tdesign` 应用：
```bash
pnpm dev:tdesign
```
运行 `docs` 应用： 运行 `docs` 应用：
```bash ```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` - `apps\web-antd\package.json`
@ -173,7 +193,7 @@ pnpm dev:docs
}, },
``` ```
增加命令`"build:test"`, 并将原`"build"`改为`"build:prod"`以避免同时构建两个环境的包。 增加命令 `"build:test"`，并将原 `"build"` 改为 `"build:prod"` 以避免同时构建两个环境的包。
- `package.json` - `package.json`
@ -188,7 +208,7 @@ pnpm dev:docs
} }
``` ```
在根目录`package.json`中加入构建测试环境的命令 在根目录 `package.json` 中加入构建测试环境的命令。
- `turbo.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"`。 需要将资源放在对应项目的 `public/static` 目录下。引入的路径为：`src="/static/xxx.png"`。
## DevTools ## DevTools
项目内置了 [Vue DevTools](https://github.com/vuejs/devtools-next) 插件，可以在开发过程中使用。默认关闭，可在`.env.development` 内开启，并重新运行项目即可： 项目内置了 [Vue DevTools](https://github.com/vuejs/devtools-next) 插件，可以在开发过程中使用。默认关闭，可在 `.env.development` 内开启，并重新运行项目即可：
```bash ```bash
VITE_DEVTOOLS=true VITE_DEVTOOLS=true
@ -251,7 +271,7 @@ pnpm dev:docs
```bash ```bash
# 请在项目根目录下执行 # 请在项目根目录下执行
# 该命令会删除整个仓库所有的 node_modules、yarn.lock、package.lock.json后 # 该命令会删除整个仓库所有的 node_modules、yarn.lock、package-lock.json 后
# 再进行依赖重新安装（安装速度会明显变慢）。 # 再进行依赖重新安装（安装速度会明显变慢）。
pnpm reinstall pnpm reinstall
``` ```

6
docs/src/guide/introduction/vben.md
View File

@ -20,9 +20,9 @@
- **动态菜单**：支持动态菜单，可以根据权限配置显示菜单。 - **动态菜单**：支持动态菜单，可以根据权限配置显示菜单。
- **Mock 数据**：基于 `Nitro` 的本地高性能 Mock 数据方案。 - **Mock 数据**：基于 `Nitro` 的本地高性能 Mock 数据方案。
- **组件丰富**：提供了丰富的组件，可以满足大部分的业务需求。 - **组件丰富**：提供了丰富的组件，可以满足大部分的业务需求。
- **规范**：代码规范，使用 `ESLint`、`Prettier`、`Stylelint`、`Publint`、`CSpell` 等工具保证代码质量。 - **规范**：代码规范，使用 `Oxfmt`、`Oxlint`、`ESLint`、`Stylelint`、`Publint`、`CSpell` 等工具保证代码质量。
- **工程化**：使用 `Pnpm Monorepo`、`TurboRepo`、`Changeset` 等工具，提高开发效率。 - **工程化**：使用 `Pnpm Monorepo`、`Turborepo`、`Changeset` 等工具，提高开发效率。
- **多UI库支持**：支持 `Ant Design Vue`、`Element Plus`、`Naive` 等主流 UI 库，不再限制于特定框架。 - **多UI库支持**：支持 `Ant Design Vue`、`Ant Design Vue Next`、`Element Plus`、`Naive UI`、`TDesign` 等主流 UI 库，不再限制于特定框架。
## 浏览器支持 ## 浏览器支持

2
docs/src/guide/introduction/why.md
View File

@ -20,4 +20,4 @@
## 质量与规范 ## 质量与规范
我们始终高度重视代码的质量与规范。通过使用 ESLint、Prettier、Stylelint、Publint、CSpell 等工具来确保代码质量。我们的代码规范基于 Vue3、Vite、TypeScript 等现代前端技术制定，旨在提供一个简洁、易用的框架，使开发者能够快速上手并专注于业务逻辑的开发。 我们始终高度重视代码的质量与规范。通过使用 Oxfmt、Oxlint、ESLint、Stylelint、Publint、CSpell 等工具来确保代码质量。我们的代码规范基于 Vue3、Vite、TypeScript 等现代前端技术制定，旨在提供一个简洁、易用的框架，使开发者能够快速上手并专注于业务逻辑的开发。

96
docs/src/guide/project/dir.md
View File

@ -4,65 +4,69 @@
```bash ```bash
. .
├── Dockerfile # Docker 镜像构建文件
├── README.md # 项目说明文档 ├── README.md # 项目说明文档
├── apps # 项目应用目录 ├── apps # 项目应用目录
│   ├── backend-mock # 后端模拟服务应用 │ ├── backend-mock # 后端模拟服务应用
│   ├── web-antd # 基于 Ant Design Vue 的前端应用 │ ├── web-antd # 基于 Ant Design Vue 的前端应用
│   ├── web-ele # 基于 Element Plus 的前端应用 │ ├── web-antdv-next # 基于 Ant Design Vue Next 的前端应用
│   └── web-naive # 基于 Naive UI 的前端应用 │ ├── web-ele # 基于 Element Plus 的前端应用
├── build-local-docker-image.sh # 本地构建 Docker 镜像脚本 │ ├── web-naive # 基于 Naive UI 的前端应用
│ └── web-tdesign # 基于 TDesign 的前端应用
├── cspell.json # CSpell 配置文件 ├── cspell.json # CSpell 配置文件
├── docs # 项目文档目录 ├── docs # 项目文档目录
├── eslint.config.mjs # ESLint 配置文件 ├── eslint.config.mjs # ESLint 配置文件
├── lefthook.yml # Git Hook 配置文件
├── internal # 内部工具目录 ├── internal # 内部工具目录
│   ├── lint-configs # 代码检查配置 │ ├── lint-configs # 代码检查配置
│   │   ├── commitlint-config # Commitlint 配置 │ │ ├── commitlint-config # Commitlint 配置
│   │   ├── eslint-config # ESLint 配置 │ │ ├── eslint-config # ESLint 配置
│   │   ├── prettier-config # Prettier 配置 │ │ ├── oxfmt-config # Oxfmt 配置
│   │   └── stylelint-config # Stylelint 配置 │ │ ├── oxlint-config # Oxlint 配置
│   ├── node-utils # Node.js 工具 │ │ └── stylelint-config # Stylelint 配置
│   ├── tailwind-config # Tailwind 配置 │ ├── node-utils # Node.js 工具
│   ├── tsconfig # 通用 tsconfig 配置 │ ├── tsconfig # 通用 tsconfig 配置
│   └── vite-config # 通用Vite 配置 │ └── vite-config # 通用 Vite 配置
├── oxfmt.config.ts # Oxfmt 配置入口
├── oxlint.config.ts # Oxlint 配置文件
├── package.json # 项目依赖配置 ├── package.json # 项目依赖配置
├── packages # 项目包目录 ├── packages # 项目包目录
│   ├── @core # 核心包 │ ├── @core # 核心包
│   │   ├── base # 基础包 │ │ ├── base # 基础包
│   │   │   ├── design # 设计相关 │ │ │ ├── design # 设计相关
│   │   │   ├── icons # 图标 │ │ │ ├── icons # 图标
│   │   │   ├── shared # 共享 │ │ │ ├── shared # 共享
│   │   │   └── typings # 类型定义 │ │ │ └── typings # 类型定义
│   │   ├── composables # 组合式 API │ │ ├── composables # 组合式 API
│   │   ├── preferences # 偏好设置 │ │ ├── preferences # 偏好设置
│   │   └── ui-kit # UI 组件集合 │ │ └── ui-kit # UI 组件集合
│   │   ├── layout-ui # 布局 UI │ │ ├── layout-ui # 布局 UI
│   │   ├── menu-ui # 菜单 UI │ │ ├── menu-ui # 菜单 UI
│   │   ├── shadcn-ui # shadcn UI │ │ ├── shadcn-ui # shadcn UI
│   │   └── tabs-ui # 标签页 UI │ │ └── tabs-ui # 标签页 UI
│   ├── constants # 常量 │ ├── constants # 常量
│   ├── effects # 副作用相关包 │ ├── effects # 副作用相关包
│   │   ├── access # 访问控制 │ │ ├── access # 访问控制
│   │   ├── plugins # 第三方大型依赖插件 │ │ ├── plugins # 第三方大型依赖插件
│   │   ├── common-ui # 通用 UI │ │ ├── common-ui # 通用 UI
│   │   ├── hooks # 组合式 API │ │ ├── hooks # 组合式 API
│   │   ├── layouts # 布局 │ │ ├── layouts # 布局
│   │   └── request # 请求 │ │ └── request # 请求
│   ├── icons # 图标 │ ├── icons # 图标
│   ├── locales # 国际化 │ ├── locales # 国际化
│   ├── preferences # 偏好设置 │ ├── preferences # 偏好设置
│   ├── stores # 状态管理 │ ├── stores # 状态管理
│   ├── styles # 样式 │ ├── styles # 样式
│   ├── types # 类型定义 │ ├── types # 类型定义
│   └── utils # 工具 │ └── utils # 工具
├── playground # 演示目录 ├── playground # 演示目录
├── pnpm-lock.yaml # pnpm 锁定文件 ├── pnpm-lock.yaml # pnpm 锁定文件
├── pnpm-workspace.yaml # pnpm 工作区配置文件 ├── pnpm-workspace.yaml # pnpm 工作区配置文件
├── scripts # 脚本目录 ├── scripts # 脚本目录
│   ├── turbo-run # Turbo 运行脚本 │ ├── deploy # 部署相关脚本
│   └── vsh # VSH 脚本 │ ├── turbo-run # Turbo 运行脚本
│ └── vsh # VSH 脚本
├── stylelint.config.mjs # Stylelint 配置文件 ├── stylelint.config.mjs # Stylelint 配置文件
├── turbo.json # Turbo 配置文件 ├── turbo.json # Turbo 配置文件
├── vben-admin.code-workspace # VS Code 工作区配置文件 ├── vben-admin.code-workspace # VS Code 工作区配置文件
└── vitest.config.ts # Vite 配置文件 └── vitest.config.ts # Vitest 配置文件
``` ```

123
docs/src/guide/project/standard.md
View File

@ -5,9 +5,9 @@
- 如果你想向项目贡献代码，请确保你的代码符合项目的代码规范。 - 如果你想向项目贡献代码，请确保你的代码符合项目的代码规范。
- 如果你使用的是 `vscode`，需要安装以下插件： - 如果你使用的是 `vscode`，需要安装以下插件：
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - 脚本代码检查 - [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) - 单词语法检查 - [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 样式检查 - [Stylelint](https://stylelint.io/) 用于 CSS 样式检查
- [Prettier](https://prettier.io/) 用于代码格式化
- [Commitlint](https://commitlint.js.org/) 用于检查 git 提交信息的规范 - [Commitlint](https://commitlint.js.org/) 用于检查 git 提交信息的规范
- [Publint](https://publint.dev/) 用于检查 npm 包的规范 - [Publint](https://publint.dev/) 用于检查 npm 包的规范
- [Cspell](https://cspell.org/) 用于检查拼写错误 - [Cspell](https://cspell.org/) 用于检查拼写错误
- [lefthook](https://github.com/evilmartians/lefthook) 用于管理 Git hooks，在提交前自动运行代码校验和格式化 - [lefthook](https://github.com/evilmartians/lefthook) 用于管理 Git hooks，在提交前自动运行代码校验和格式化
## ESLint ## Oxfmt
ESLint 是一个代码规范和错误检查工具，用于识别和报告 TypeScript 代码中的语法错误。 Oxfmt 用于统一项目代码风格，统一缩进、引号、尾逗号等格式。
### 命令 ### 命令
```bash ```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` 目录下，可以根据项目需求进行修改。
## Stylelint ## Oxlint
Oxlint 是当前仓库的主要脚本 lint 工具，用于识别和报告 JavaScript / TypeScript 代码中的问题。
### 命令
```bash
pnpm oxlint
pnpm oxlint --fix
```
Stylelint 用于校验项目内部 css 的风格,加上编辑器的自动修复，可以很好的统一项目内部 css 风格 ### 配置
Oxlint 的核心配置位于 `internal/lint-configs/oxlint-config` 目录下，根目录入口文件为 `oxlint.config.ts`。
## ESLint
ESLint 用于补充 Vue、JSONC、YAML 等规则检查。
### 命令 ### 命令
```bash ```bash
pnpm stylelint "**/*.{vue,css,less.scss}" pnpm eslint . --cache
``` ```
### 配置 ### 配置
Stylelint 配置文件为 `stylelint.config.mjs`，其核心配置放在`internal/lint-configs/stylelint-config`目录下，可以根据项目需求进行修改。 ESLint 配置文件为 `eslint.config.mjs`，其核心配置放在 `internal/lint-configs/eslint-config` 目录下，可以根据项目需求进行修改。
## Prettier ## Stylelint
Prettier 可以用于统一项目代码风格，统一的缩进，单双引号，尾逗号等等风格 Stylelint 用于校验项目内部 CSS 的风格，加上编辑器的自动修复，可以很好的统一项目内部 CSS 风格。
### 命令 ### 命令
```bash ```bash
pnpm prettier . pnpm stylelint "**/*.{vue,css,less,scss}" --cache
``` ```
### 配置 ### 配置
Prettier 配置文件为 `.prettier.mjs`，其核心配置放在`internal/lint-configs/prettier-config`目录下，可以根据项目需求进行修改。 Stylelint 配置文件为 `stylelint.config.mjs`，其核心配置放在 `internal/lint-configs/stylelint-config` 目录下，可以根据项目需求进行修改。
## CommitLint ## 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 提交规范 ### Git 提交规范
参考 [Angular](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular) 参考 [Angular](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular)
- `feat` 增加新功能 - `feat` 增加新功能
- `fix` 修复问题/BUG - `fix` 修复问题 / BUG
- `style` 代码风格相关无影响运行结果的 - `style` 代码风格相关无影响运行结果的
- `perf` 优化/性能提升 - `perf` 优化 / 性能提升
- `refactor` 重构 - `refactor` 重构
- `revert` 撤销修改 - `revert` 撤销修改
- `test` 测试相关 - `test` 测试相关
- `docs` 文档/注释 - `docs` 文档 / 注释
- `chore` 依赖更新/脚手架配置修改等 - `chore` 依赖更新 / 脚手架配置修改等
- `workflow` 工作流改进 - `workflow` 工作流改进
- `ci` 持续集成 - `ci` 持续集成
- `types` 类型修改 - `types` 类型修改
### 关闭Git提交规范检查 ### 关闭 Git 提交规范检查
如果你想关闭 Git 提交规范检查，有两种方式： 如果你想关闭 Git 提交规范检查，有两种方式：
@ -112,21 +129,29 @@ CommitLint 配置文件为 `.commitlintrc.mjs`，其核心配置放在`internal/
git commit -m 'feat: add home page' --no-verify git commit -m 'feat: add home page' --no-verify
``` ```
```bash [永久关闭] ```yaml [长期关闭]
# 在 .husky/commit-msg 内注释以下代码即可 commit-msg:
pnpm exec commitlint --edit "$1" # [!code --] commands:
# commitlint:
# run: pnpm exec commitlint --edit $1
``` ```
::: :::
如果修改了 `lefthook.yml`，请重新执行：
```bash
pnpm exec lefthook install
```
## Publint ## Publint
Publint 是一个用于检查 npm 包的规范的工具，可以检查包的版本号是否符合规范，是否符合标准的 ESM 规范包等等。 Publint 是一个用于检查 npm 包规范的工具，可以检查包的版本号、导出方式以及 ESM 包结构等问题。
### 命令 ### 命令
```bash ```bash
pnpm vsh publint pnpm publint
``` ```
## Cspell ## Cspell
@ -136,7 +161,7 @@ Cspell 是一个用于检查拼写错误的工具，可以检查代码中的拼
### 命令 ### 命令
```bash ```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
git hook 一般结合各种 lint，在 git 提交代码的时候进行代码风格校验，如果校验没通过，则不会进行提交。需要开发者自行修改后再次进行提交 git hook 一般结合各种 lint，在 git 提交代码的时候进行代码风格校验，如果校验没通过，则不会进行提交。需要开发者自行修改后再次进行提交。
### lefthook ### lefthook
有一个问题就是校验会校验全部代码，但是我们只想校验我们自己提交的代码，这个时候就可以使用 lefthook。 有一个问题就是校验会校验全部代码，但是我们只想校验我们自己提交的代码，这个时候就可以使用 lefthook。
最有效的解决方案就是将 Lint 校验放到本地，常见做法是使用 lefthook 在本地提交之前先做一次 Lint 校验。 最有效的解决方案就是将 lint 校验放到本地，常见做法是使用 lefthook 在本地提交之前先做一次 lint 校验。
项目在 `lefthook.yml` 内部定义了相应的 hooks： 项目在 `lefthook.yml` 内部定义了相应的 hooks：
@ -159,52 +184,46 @@ git hook 一般结合各种 lint，在 git 提交代码的时候进行代码风
- `code-workspace`: 更新 VSCode 工作区配置 - `code-workspace`: 更新 VSCode 工作区配置
- `lint-md`: 格式化 Markdown 文件 - `lint-md`: 格式化 Markdown 文件
- `lint-vue`: 格式化并检查 Vue 文件 - `lint-vue`: 格式化并检查 Vue 文件
- `lint-js`: 格式化并检查 JavaScript/TypeScript 文件 - `lint-js`: 格式化并检查 JavaScript / TypeScript 文件
- `lint-style`: 格式化并检查样式文件 - `lint-style`: 格式化并检查样式文件
- `lint-package`: 格式化 package.json - `lint-package`: 格式化 `package.json`
- `lint-json`: 格式化其他 JSON 文件 - `lint-json`: 格式化其他 JSON 文件
- `post-merge`: 在合并后运行，用于自动安装依赖 - `post-merge`: 在合并后运行，用于自动安装依赖
- `install`: 运行 `pnpm install` 安装新依赖 - `install`: 运行 `pnpm install` 安装新依赖
- `commit-msg`: 在提交时运行，用于检查提交信息格式 - `commit-msg`: 在提交时运行，用于检查提交信息格式
- `commitlint`: 使用 commitlint 检查提交信息 - `commitlint`: 使用 commitlint 检查提交信息
#### 如何关闭 lefthook 当前 hooks 可通过以下命令安装：
如果你想关闭 lefthook，有两种方式： ```bash
pnpm exec lefthook install
```
::: code-group #### 如何关闭 lefthook
```bash [临时关闭] 如果你想临时关闭 lefthook，可以使用：
git commit -m 'feat: add home page' --no-verify
```
```bash [永久关闭] ```bash
# 删除 lefthook.yml 文件即可 git commit -m 'feat: add home page' --no-verify
rm lefthook.yml
``` ```
:::
#### 如何修改 lefthook 配置 #### 如何修改 lefthook 配置
如果你想修改 lefthook 的配置，可以编辑 `lefthook.yml` 文件。例如： 如果你想修改 lefthook 的配置，可以编辑 `lefthook.yml` 文件。例如：
```yaml ```yaml
pre-commit: pre-commit:
parallel: true # 并行执行任务 parallel: true
jobs: commands:
- name: lint-js lint-js:
run: pnpm prettier --cache --ignore-unknown --write {staged_files} run: pnpm oxfmt {staged_files} && pnpm oxlint --fix {staged_files} && pnpm eslint --cache --fix {staged_files}
glob: '*.{js,jsx,ts,tsx}' glob: '*.{js,jsx,ts,tsx}'
``` ```
其中： 其中：
- `parallel`: 是否并行执行任务 - `parallel`: 是否并行执行任务
- `jobs`: 定义要执行的任务列表 - `commands`: 定义要执行的任务列表
- `name`: 任务名称
- `run`: 要执行的命令 - `run`: 要执行的命令
- `glob`: 匹配的文件模式 - `glob`: 匹配的文件模式
- `{staged_files}`: 表示暂存的文件列表 - `{staged_files}`: 表示暂存的文件列表

33
docs/src/guide/project/tailwindcss.md
View File

@ -1,17 +1,38 @@
# Tailwind CSS # 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`
项目对 Vue 单文件组件中的 `@apply` 做了统一处理，相关逻辑位于：
- `internal/vite-config/src/plugins/tailwind-reference.ts`
现`tailwindcss`已至v4.x版本，使用方法与`tailwindcss: ^3.4.17`有差异，v4.0无法与v3.x版本兼容，在开发前请确认`package.json`中的`tailwindcss`版本。 当组件样式中使用 `@apply` 时，会自动注入对应的 `@reference`，一般不需要手动补充。

Write Preview
Loading…
Cancel
Save