https://github.com/zhyt1985/vue-health
Diagnose and fix performance issues in your Vue app
https://github.com/zhyt1985/vue-health
Last synced: 2 months ago
JSON representation
Diagnose and fix performance issues in your Vue app
- Host: GitHub
- URL: https://github.com/zhyt1985/vue-health
- Owner: zhyt1985
- Created: 2026-02-18T15:14:40.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-19T18:35:59.000Z (4 months ago)
- Last Synced: 2026-02-19T21:33:36.415Z (4 months ago)
- Language: TypeScript
- Size: 92.8 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# vue-health
English | [中文](./README.zh-CN.md)
One command to diagnose your Vue codebase health.
```bash
npx vue-health .
```
```
vue-health v2.1.0
Nuxt (Vue ^3.5.0) · 128 source files
✔ Found 12 lint issues
✔ Found 3 dead code issues
✗ Mutating props directly
Use `emit('update:propName', newValue)` or a local data copy
⚠ Unused component (3)
Remove the unused component import or use it in the template
⚠ Using v-if with v-for (2)
Move v-if to a wrapper element or use computed to filter the list
────────────────────────────────────────
( ◕‿◕) Vue Doctor — my-app
Score: 87/100 Good
███████████████████████████████████████████░░░░░░░
Framework: Nuxt · Vue: ^3.5.0 · Issues: 15 · Time: 1.2s
```
## Features
- **Fast** — powered by [oxlint](https://oxc.rs) (Rust), not ESLint
- **40+ Vue rules** — correctness, performance, security, dead code
- **Zero config** — auto-detects Nuxt / Vite / Vue CLI / Quasar
- **Dead code detection** — unused files, exports, and types via [knip](https://knip.dev)
- **Diff mode** — only scan changed files on your branch
- **Monorepo support** — select which workspace projects to scan
- **Programmable** — `import { diagnose } from "vue-health/api"`
## Claude Code Skill
vue-health also provides a [Claude Code](https://claude.ai/code) Skill, allowing you to diagnose Vue project health directly within Claude Code.
### Installation
```bash
# Clone the repository
git clone https://github.com/zhyt1985/vue-health.git ~/vue-health
# Copy the skill to Claude's global skills directory
cp -r ~/vue-health/skills/vue-health ~/.claude/skills/
```
### Usage
In Claude Code, simply ask:
```
Check the health of this Vue project
```
For more details, see [Skill Documentation](https://github.com/zhyt1985/vue-health/tree/main/skills/vue-health).
## Install
```bash
# Run directly (no install needed)
npx vue-health .
# Or install globally
npm i -g vue-health
```
Requires Node.js >= 20.
## CLI
```
Usage: vue-health [options] [directory]
Arguments:
directory project directory to scan (default: ".")
Options:
-v, --version display the version number
--no-lint skip linting
--no-dead-code skip dead code detection
--verbose show file details per rule
--score output only the score
-y, --yes skip prompts, scan all workspace projects
--project select workspace project (comma-separated)
--diff [base] scan only files changed vs base branch
-h, --help display help for command
```
### Examples
```bash
# Scan current directory
vue-health .
# Only show the score (useful in CI)
vue-health . --score
# Scan only changed files vs main
vue-health . --diff
# Scan with file-level details
vue-health . --verbose
# Skip dead code detection
vue-health . --no-dead-code
# Scan a specific workspace project
vue-health . --project my-app
```
## Node.js API
```ts
import { diagnose } from "vue-health/api";
const { diagnostics, score } = await diagnose("./my-vue-app");
console.log(score);
// { score: 87, label: "Good" }
console.log(diagnostics[0]);
// {
// filePath: "src/components/Foo.vue",
// rule: "no-mutating-props",
// severity: "error",
// message: "Mutating props directly",
// help: "Use emit('update:propName', newValue) or a local data copy",
// category: "Correctness",
// line: 42,
// column: 5
// }
```
## Rules
### Correctness
| Rule | Description |
|------|-------------|
| `no-mutating-props` | Don't mutate props directly |
| `no-ref-as-operand` | Use `.value` to access refs in script |
| `no-setup-props-reactivity-loss` | Maintain reactivity when destructuring props |
| `no-side-effects-in-computed-properties` | Computed properties should be pure |
| `no-async-in-computed-properties` | No async in computed — use watchers |
| `no-lifecycle-after-await` | Lifecycle hooks must be before `await` in setup |
| `no-watch-after-await` | `watch()` must be before `await` in setup |
| `no-shared-component-data` | `data()` must return a fresh object |
| `no-dupe-keys` | No duplicate keys across data/computed/methods |
| `return-in-computed-property` | Computed properties must return a value |
| `valid-v-model` | v-model needs a writable expression |
| `valid-v-for` / `valid-v-if` / `valid-v-on` / `valid-v-bind` / `valid-v-slot` | Template directive validation |
| `require-v-for-key` | `:key` is required on v-for elements |
| ... | 40+ rules total |
### Performance
| Rule | Description |
|------|-------------|
| `no-use-v-if-with-v-for` | Don't use v-if and v-for on the same element |
### Security
| Rule | Description |
|------|-------------|
| `no-v-html` | `v-html` can lead to XSS — sanitize or use interpolation |
### Dead Code (via knip)
| Rule | Description |
|------|-------------|
| `no-unused-components` | Remove unused component imports |
| `no-unused-vars` | Remove unused variables |
| Unused files | Files not imported anywhere |
| Unused exports / types | Exported symbols never consumed |
## Scoring
Score is 0–100, calculated from diagnostic count and severity:
| Range | Label | Indicator |
|-------|-------|-----------|
| 75–100 | Good | `( ◕‿◕)` |
| 50–74 | OK | `( ◑‿◑)` |
| 0–49 | Needs Work | `( ◉_◉)` |
Errors weigh 3x more than warnings.
## Configuration
Create `.vue-healthrc` or `.vue-healthrc.json` in your project root:
```json
{
"lint": true,
"deadCode": true,
"verbose": false,
"diff": false,
"ignore": {
"rules": ["no-v-html"],
"files": ["src/legacy/**"]
}
}
```
## Supported Frameworks
Auto-detected from `package.json` or config files:
- **Nuxt** — `nuxt.config.ts`
- **Vite** — `vite.config.ts`
- **Vue CLI** — `vue.config.js`
- **Quasar** — `@quasar/app-vite` or `@quasar/app-webpack`
Also detects TypeScript (`tsconfig.json`) and Vue version.
## License
MIT