CLI
Run vite-doctor from the project root to get Vite, Vue, Nuxt, and Nitro diagnostics.
Install dependencies first. The CLI does not run package-manager install commands.
Doctor resolves the runtime that the framework actually loads. In a Nuxt project, it follows the installed Nuxt package to its Nitro package and then follows Nitro to H3, so Nitro 3 or H3 v2 advice does not appear for an installed Nitro 2 or H3 v1 runtime. If Doctor cannot identify a runtime safely, it reports the unresolved inventory and suppresses version-specific diagnostics.
Run diagnostics
pnpm dlx vite-doctor .
Narrow the Doctor Run when you need changed files, strict CI failure behavior, one Rule, or safe fixes:
pnpm dlx vite-doctor . --changed
pnpm dlx vite-doctor . --max-warnings 0
pnpm dlx vite-doctor . --strict
pnpm dlx vite-doctor . --rules nuxt/fetch/no-raw-fetch-in-setup
pnpm dlx vite-doctor . --fix
--changed includes staged, unstaged, and untracked files against HEAD. --since <ref> uses the merge base with that ref. Doctor filters a full run's Diagnostics to those with a primary or related location on a changed line, including locations in package.json and pnpm-lock.yaml. A project-scoped Rule's Diagnostic can also qualify through a changed manifest or lockfile entry it cites as evidence. For example, a new required peer can bring PKG0007 into a dependent package's report, and a lockfile resolution that adds a second copy of a singleton can bring PKG0008. A package-local run can use this evidence from its workspace without reporting findings for sibling packages. Ordinary file Rules stay limited to their own changed lines. Diagnostics without a source range are included when the file they are anchored to changed; manifest Rules anchor project-level findings to the first source file, as in a full run. Parser evidence gaps are reported for changed files only, and the report has no workspace graph summary unless --analyses dead-code or graph is requested.
File Rules that report only into the file they analyze (the default report scope) run on the changed files only. Rules that declare a project report scope, manifest and workspace Rules, and --analyses keep whole-project context, and unchanged files are parsed only for them. With the analysis cache, those project-wide results are recomputed only where a recorded Rule input changed. A Git failure stops the run instead of returning a false clean result.
In a workspace declared by pnpm-workspace.yaml or the workspaces field, Doctor reads every workspace package's package.json, and each package activates Rule Packs from its own dependencies. A Rule Pack runs its file Rules on the files of the packages that activate it, the root included, so a nitro devDependency at the root checks the root's own files only. A Rule that declares meta.activationScope: "workspace", such as nitro/config/require-absolute-generated-paths, checks every workspace package once its Rule Pack activates anywhere, because the integration code it checks lives outside the packages that run the framework. If the root depends on Nitro and packages/app depends on Vue, the Vue Rules check packages/app only. The JSON and agent reports list each workspace package with its framework and activated Rule Packs under workspacePackages, and the top-level framework is the workspace root's own framework. Passing --framework applies only that framework's Rule Packs, to the whole workspace.
A workspace package is a Nuxt app when it has a nuxt.config or a .nuxt/doctor.manifest.json, lists nuxt in dependencies, or has nuxt in devDependencies with an app.vue or pages/ entry. A Nuxt module package, whose main entry builds from a src/ file that default-exports defineNuxtModule(), counts as Nuxt too, so the module-authoring Rules run on it. A package that depends on @nuxt/kit or exports ./nuxt without being an app ships a Nuxt module: it keeps its own framework, is marked nuxtIntegration: true, and activates the Vue, Nitro, and Nuxt Rule Packs for the code it ships into Nuxt apps. Nuxt routing Rules such as nuxt/routing/prefer-nuxt-useroute check Nuxt app files and a Nuxt module's runtime/ directory, and skip any package that creates its own router with createRouter from vue-router.
Each Nuxt workspace package keeps its own Nuxt Project Inventory: its nuxt.config, .nuxt/doctor.manifest.json, server directories, and runtime versions. Nuxt Rules read the inventory of the package that owns the file, so a workspace with several Nuxt apps runs as one Doctor Run. Doctor options set through the vite-doctor/nuxt module of a nested Nuxt app apply only when Doctor runs from that app. A workspace run lists them under evidenceGaps.
Safe fixes are applied atomically and Doctor runs again. The final report contains the remaining Diagnostics and a count of applied or skipped edits. --unsafe-fix also applies fixes that can lose information, such as deleting a comment with typescript/strict/no-comments. Review the Diagnostics before you pass it.
If script parsing reports an error and discards source statements, Doctor marks the Run incomplete and reports the affected file and parser message, even when earlier statements were recovered. Check the source syntax and parser support before relying on the report. Diagnostics from recovered statements and successfully parsed files remain available, including on runs that reuse cached File Facts.
Vue SFC parser errors also make the Run incomplete, including duplicate component blocks and malformed template markup. Doctor retains findings from recovered component content and clears the evidence gap after repair. This does not validate preprocessed templates or every recovered script grammar error.
Use --baseline <file> --new-only to suppress fingerprints already recorded in a baseline. Doctor accepts an array of fingerprint strings or objects with a fingerprint field, an object containing a diagnostics array with version: 2 (or the older optional version: 1), or a Doctor JSON report with reportVersion: 4 or 3. In JSON reports, version identifies the Doctor package rather than the baseline format. Baselines and JSON reports record the fingerprintScheme their fingerprints were computed with, and --update-baseline also records the writing Doctor version as doctorVersion. When --new-only reads a non-empty baseline from another fingerprint scheme, or one without a recorded scheme, Doctor still applies the fingerprints that match and reports a DOC0032 warning that tells you to regenerate the baseline. An existing unreadable or malformed baseline stops the run with DOC0025 and CLI exit code 2. A missing baseline is treated as empty so a first run can initialize it through the updateBaseline Doctor Run option.
A full --new-only run reports resolved baseline entries as one info-level DOC0039 Diagnostic. Delete only the fingerprints listed in its evidence. Doctor requires the recorded Rule and file (included in baselines from --update-baseline and saved Doctor JSON reports), and checks that the file Rule covered the file or that the file no longer exists. Doctor does not report entries from workspace analyses or Rules that run or report across files. Runs with --changed, --since, --rules, --analyses, --update-baseline, or a severity threshold above info do not report DOC0039.
Analysis cache
The persistent analysis cache is on by default. Pass --no-cache to run without reading or writing it. Agent rerun commands repeat --cache or --no-cache only when the original run passed one.
The cache is one file, store.json, in .vite-doctor/cache (.nuxt/doctor/cache for Nuxt projects). It keeps File Facts and the Diagnostics of each Rule per file, together with the Rule inputs each Rule read: other files, directory listings, and path checks made through ctx.fs. A cached result is reused only when the file content, the Rule implementation, the Project Inventory, the Rule config, and every recorded input are unchanged. Doctor compares file size, modification time, change time, and inode before reading a file, so an unchanged warm run reads no source file. Rules that declare cacheScope: "none" or a non-deterministic determinism always run.
Inspect the cache with vite-doctor cache status (--format json for automation). It prints the store path, whether the current Doctor build wrote it, entry counts, and what the run that last wrote it read, parsed, reused, and computed. vite-doctor cache clean removes it.
Long-lived Doctor process
Each CLI invocation loads Doctor and reads the cache again. When an agent or script runs Doctor many times in one project, opt in to a long-lived Doctor process that keeps loaded Rule Packs and the parsed cache in memory:
export VITE_DOCTOR_SERVER=1 # every Doctor Run in this shell
pnpm vite-doctor . --server # one Doctor Run
pnpm vite-doctor . --no-server # run in this process even when enabled
The first Doctor Run starts one Doctor process per project root. Later runs reuse it, one at a time, and get the same stdout, stderr, and exit code as a direct run. The process is replaced when the Doctor version, Node.js, doctor.config.json, vite.config.*, or the CI and color environment differ from the client, and it exits after 15 minutes without runs (VITE_DOCTOR_SERVER_IDLE_MS changes the timeout).
These invocations always run directly: interactive terminals, --config, --host-extensions, --watch, and commands other than a Doctor Run. The Doctor process never loads executable configuration or host-registered Doctor Extensions.
pnpm vite-doctor server status # pid, memory, runs, and whether this CLI reuses it
pnpm vite-doctor server stop
The socket, state file, and log live in a directory private to your user under the system temporary directory; server status prints their paths.
Watch mode
vite-doctor . --watch runs Doctor, then reruns it whenever a project file changes, reusing loaded Rule Packs and the cache between runs. Each rerun prints a full report. Stop it with Ctrl+C; the exit code is that of the last run. --watch cannot be combined with --fix, --unsafe-fix, or --update-baseline.
Cache recovery after upgrading
An interrupted run of an earlier Doctor version can leave a legacy cache lock. Doctor warns when that lock blocks persistence; diagnostics still use the current source, but cache updates and pruning are skipped until cleanup.
To migrate that cache once:
- Stop all Doctor processes sharing the cache, including dev servers using a Plugin Surface and processes in other containers.
- From the project root, run
pnpm vite-doctor cache clean. Pass the same--configand--frameworkoptions used by the original run. For a Plugin Surface with an in-memory custom cache directory, usecleanCache(root, config)fromvite-doctorwith that configuration after stopping the hosts. - Restart Doctor. The next run rebuilds the cache; subsequent unchanged runs reuse it.
This explicit cleanup is required for legacy .store.lock files and lock claims without a recognized owner namespace. Those formats cannot prove whether a writer is still active, so Doctor never automatically deletes them based on age or a PID lookup. Current-format abandoned locks are recovered automatically when Doctor can establish that the owner has exited in the same PID namespace.
Workspace analyses
Use --analyses to request workspace graph, dead-code, duplication, or health Diagnostics. These analyses use the source inventory and available project entrypoints. Select one analysis or combine them with commas:
pnpm vite-doctor . --analyses graph
pnpm vite-doctor . --analyses dead-code
pnpm vite-doctor . --analyses dupes
pnpm vite-doctor . --analyses health
pnpm vite-doctor . --analyses graph,dead-code,dupes,health --format json
| Analysis | Diagnostic Reference |
|---|---|
graph | DOC0001: circular dependencies |
graph | DOC0002: repeated export names |
dead-code | DOC0003: undeclared dependencies |
dead-code | DOC0004: unresolved source imports |
dead-code | DOC0005: apparently unused dependencies |
dead-code | DOC0006: unreachable value exports |
dead-code | DOC0007: unreachable source files |
dead-code | DOC0008: unreachable type exports |
dupes | DOC0009: repeated token sequences |
health | DOC0010: file-level branch complexity |
health | DOC0011: many static imports |
Selecting --analyses alone runs the selected workspace analyses. Add --rules <rule-id> to also run a Rule from a Rule Pack. Review runtime loading, public package consumers, and host conventions before removing code based on a reachability Diagnostic. Each reference page describes its evidence and limits.
Exit codes
0: no blocking Diagnostics or errors, and the warning limit was not exceeded. The report may still contain warnings.1: Doctor found a blocker or error, or warnings exceeded--max-warnings.2: the command or configuration is invalid.3: Doctor could not collect required project evidence, including runtime resolution or source parsing. This takes precedence over Diagnostic severity.
When a command or configuration failure has a Diagnostic Code, text output includes
[CODE], JSON and agent failure reports include error.code, and SARIF execution
notifications include properties.diagnosticCode. Ordinary failures without a code,
such as malformed JSON, omit these fields. Automation can match the code without
parsing the error message.
nuxt doctor and nuxt doctor migrate exit with these codes on Nuxt 4.6 and
later, so nuxt doctor --max-warnings 0 can fail a CI job. Nuxt 4.1 to 4.5 ship a Nuxt
CLI that exits 0 after any host command. On those versions, run vite-doctor directly
in CI:
pnpm vite-doctor . --host-extensions --max-warnings 0
pnpm vite-doctor migrate . --to nuxt@5 --format json
Use Doctor from an agent
Doctor uses Vercel's agent catalog to recognize coding-agent runtimes. Non-interactive agent runs receive the compact agent report automatically. CI and interactive terminals keep text output. Pass an explicit format whenever a script needs a fixed contract:
pnpm dlx vite-doctor . --format agent
pnpm dlx vite-doctor . --format json
pnpm dlx vite-doctor . --format sarif
pnpm dlx vite-doctor . --format text
The agent report removes duplicate fields but keeps a direct remediation path. Each Diagnostic includes its message, remediation, relative location, and Diagnostic Reference URL, plus its confidence, evidence, and edit plan when the Rule gives them. Confidence comes from the Rule: proven for syntax facts, type-backed, manifest-backed, or runtime-backed when that evidence decides the finding, and heuristic-high, heuristic-medium, or heuristic-low otherwise. Evidence lists only what the Rule recorded; a Diagnostic without evidence has no evidence field. Top-level command templates cover explanation, focused verification, and the full rerun without repeating them for every finding.
For automation, use the commandArgs arrays. The first item is the executable and the remaining items are literal arguments. Replace the <code> or <rule> item as needed, then run the array without a shell from project.cwd. This preserves revision names and preset selectors containing spaces or shell syntax on every platform. The commands strings are quoted templates for POSIX shells; they are not Windows command-line encodings.
CLI verification commands retain Rule selection, severity, analyses, baseline filtering,
warning limits, cache policy, profiling, and an explicitly selected --config path.
verify replaces the Rule selector with <rule>. Both commands omit --fix,
--unsafe-fix, and baseline updates so verification does not modify source or baselines.
Doctor never discovers executable configuration when creating these commands.
API callers can provide { runOptions, configFile } to createAgentReport, or as the
third argument to createReport, to preserve the same CLI options. In-memory host
configuration and Doctor Extensions cannot be reconstructed from a command; use the
original Plugin Surface to repeat those runs.
Use the same explicit config when listing or explaining Rules from a Doctor Extension:
pnpm vite-doctor rules --config doctor.config.ts
pnpm vite-doctor explain CUSTOM0001 --config doctor.config.ts
Both commands register configured Rule Packs, including packs contributed by an
extension's setup function, without executing Rules. Executable config loading
remains explicit. Agent explanation commands retain the selected config path.
Custom codes link to the docs URL declared by their Rule Pack's
defineDoctorDiagnostics registry, or to the Rule's reference link. Doctor does not
invent a Diagnostic Reference page for a third-party code.
Nuxt modules can register Doctor Extensions through the Nuxt 4 Bridge. nuxt doctor
loads them automatically. The standalone CLI loads them only when you pass
--host-extensions, because that runs code registered by the host:
pnpm vite-doctor . --host-extensions --max-warnings 0
pnpm vite-doctor explain ACME0001 --host-extensions
Agent commands keep --host-extensions when the original run used it. See
Extending Doctor to write and ship Rules.
Check a migration before upgrading
Use migrate to evaluate the current source against the next supported runtime graph:
pnpm dlx vite-doctor migrate .
pnpm nuxt doctor migrate
Doctor infers Nuxt 5 from an installed Nuxt 4 project and Nitro 3 from an installed Nitro 2 project. Pass an explicit target when Doctor cannot infer one unambiguous next step:
pnpm dlx vite-doctor migrate . --to nuxt@5
pnpm dlx vite-doctor migrate . --to nitro@3
The report separates source changes that are safe on the installed runtime, dependency, configuration, and source changes that must land together, and checks that require the target runtime to be installed. The command diagnoses only; it does not rewrite source or dependencies.
Use JSON for automation or migration tooling:
pnpm dlx vite-doctor migrate . --to nuxt@5 --format json
Configuration
Doctor needs no config file. It activates Rule Packs from the project's dependencies, so vite-doctor . works on its own. Add config only to change rules, per-path overrides, suppressions, include or exclude globs, or Config Extends presets. Doctor reports an info-level DOC0038 Diagnostic when it discovers a doctor.config.json that only repeats defaults, so the run is the same without it. Delete the file unless a script or CI job passes it with --config. It doesn't suggest deletion for an explicit --config or when the file replaces non-default host settings.
Doctor reads two config sources without running project code. The first is doctor.config.json:
{
"rules": {
"vite/define/no-secret-define": "error"
}
}
A Rule entry is "off", a severity ("blocker", "error", "warn", "info"), or a [severity, options] tuple. A severity also turns on a Rule that no selected preset includes, so "vue/props/no-unused-props": "warn" runs that strict-only Rule without the rest of vue/strict. With "extends": [], a config runs exactly the Rules it names.
The Diagnostics Doctor reports about its own inputs take "off" or a severity in rules and in overrides too, so "doctor/inline/unused-suppression": "error" fails the run on a stale directive and "off" keeps --fix from removing its unused Rule IDs. They are doctor/inventory/unresolved-runtime (DOC0022), doctor/config/unused-suppression (DOC0031), doctor/baseline/stale-fingerprint-scheme (DOC0032), doctor/inventory/empty-sfc (DOC0033), doctor/inline/unused-suppression (DOC0036), doctor/inline/unknown-suppression-rule (DOC0037), doctor/config/default-config-file (DOC0038) and doctor/baseline/resolved-entries (DOC0039). They take no options. An unregistered doctor/ Rule ID outside this list stops the run with DOC0020.
Configure DOC0038 through an inherited source such as a Nuxt manifest: adding the setting to doctor.config.json makes that file non-default, so the Diagnostic no longer applies. DOC0039 still requires a full run that includes info findings, even if you raise its severity: otherwise Doctor cannot tell whether a baseline entry was resolved or filtered out.
By default Doctor analyzes .vue, .ts, .tsx, .js and .jsx files and their module variants, plus content/ Markdown when the project uses Nuxt Content. It skips node_modules, dist, .nuxt, .next, .output, coverage, test-results, playwright-report, public and generated folders, *.generated.* and minified files, fixtures, __snapshots__, type-test folders (test-d, dts-test, type-tests and similar), doctor.config.*, files .gitignore excludes, and files whose header says they are generated. Test code is skipped too: files in test, tests, __tests__ and test-utils folders, and *.test.* and *.spec.* files. A Rule that declares meta.includeTestFiles also checks test code, and no other Rule or analysis sees it. include replaces the default file globs, and exclude adds to the skipped paths, so a path you exclude is never analyzed, test code included. scope.files in the report counts test files only when a Rule checked them.
Use overrides to configure Rules for some paths only, such as library code against playgrounds and docs. Each override has files, a list of globs relative to the project root, and optional rules and extends. Overrides apply in order after the top-level config, so a later matching override wins:
{
"extends": ["vite-doctor/typescript/recommended"],
"overrides": [
{
"files": ["packages/*/src/**"],
"rules": { "typescript/boundaries/no-cross-realm-web-instanceof": "error" }
},
{
"files": ["playground/**", "docs/**"],
"rules": { "typescript/evidence/no-chained-type-assertions": "off" }
}
]
}
In an override, extends enables a Preset's Rules, including Rules turned off earlier. The same override's rules entries take precedence over its extends: "off" turns a Rule off, and a severity turns it on or changes its severity. These changes keep any earlier Rule options unless a new tuple supplies options. When "auto" activates a Rule Pack for only some workspace packages, overrides cannot widen that scope. A top-level rules entry that enables a Rule no selected Preset includes, an explicit top-level Preset, and Rules with workspace-wide Activation are not subject to that automatic package limit.
Overrides apply to the physical file a Diagnostic is located in, including Diagnostics from manifest and workspace Rules. Rule options in override tuples apply to the source being analyzed by file Rules. For all other Rules, set options in top-level rules; override tuples with options for those Rules fail with DOC0035. Use exclude instead when a path should not be analyzed at all. The Vite plugin and the Nuxt module take the same overrides in their config and doctor options. Malformed override entries fail with DOC0035.
The second is the doctor key of vite.config.*, which keeps Doctor config next to the rest of a Vite or Vite+ toolchain:
import { defineConfig } from "vite-plus";
import { defineDoctorConfig } from "vite-doctor";
export default defineConfig({
doctor: defineDoctorConfig({
rules: {
"vite/define/no-secret-define": "error",
},
}),
});
Doctor parses vite.config.* in the checked directory instead of running it. It doesn't follow imports, so it ignores a doctor key supplied only by an imported base config. An automatically discovered doctor.config.json still applies; the CLI uses defaults only when no Doctor config applies.
When the export is not static, a doctor key at any depth, a .doctor property read or write, a destructured { doctor }, or defineDoctorConfig() makes it a config error. Without those references, exports using mergeConfig(), spreads, conditional returns, or the doctor() plugin generally don't block a CLI run. Doctor checks unresolved computed keys only when it can statically resolve the export to a single config object. It does not follow conditional return paths to discover computed keys. For dynamic settings, select a Doctor config with --config or use the doctor() Vite plugin.
To read the Doctor settings, Doctor accepts an exported object or a function that directly returns one, optionally wrapped in defineConfig() imported from vite, vite-plus, or vitest/config. A block-bodied function must end in a direct return and may have variable declarations or expression statements before it. Use export default, a top-level const used only as the default export or as the defineConfig() argument, or a single top-level module.exports assignment.
The doctor value must be a literal: strings, numbers, booleans, null, arrays, and objects, optionally wrapped in defineDoctorConfig() imported from vite-doctor or vite-doctor/config. If Doctor cannot establish whether such a file exports a doctor key or what its value is, it reports a config error with the line number. For example, mergeConfig(), conditional returns, or a spread that can supply or replace the key are indeterminate. For these Vite configs, use --config doctor.config.json to select the JSON file explicitly (use {} for defaults). Otherwise, define config in only one place: when both sources are discovered, Doctor stops with a config error instead of picking one. The doctor() Vite plugin reads the same key when its own config option is not set. See Run Doctor with Vite+ for running Doctor through vp.
Inline doctor-disable directives apply only to Diagnostics with source ranges. A doctor-disable-next-line <rule> -- <reason> directive applies to the next line that contains code, so comments such as // SAFETY: notes and blank lines can sit between the directive and the code it covers. To suppress a Diagnostic without a source range, add a suppressions entry with its ruleId, optional file, and a reason. When a full Doctor Run of the suppressed Rule matches nothing, Doctor reports the stale entry as an info-level DOC0031 Diagnostic so it can be deleted. Runs with --changed, --since, --rules, or --analyses never report DOC0031, entries whose file was excluded or could not be parsed are reported only when that path no longer exists, and entries without a ruleId are reported only when the run uses auto or strict and turns no Rule off.
Doctor also reports inline directives that suppress nothing. When a file Rule named in a directive ran on that file and reported nothing the directive covers, Doctor reports an info-level DOC0036 Diagnostic. Rules without confirmed file coverage, including workspace and manifest Rules, never make a directive stale. --changed and --since runs report only directives inside the change. A directive that names an unknown Rule ID in a loaded Rule Pack's namespace, or a Diagnostic Code instead of a Rule ID, gets DOC0037. vite-doctor . --fix removes either kind of ID when the edit is safe. When removal could change how another directive applies, Doctor offers a suggestion instead.
In JSX and Vue templates, a fix can leave an empty expression or comment to preserve how surrounding text renders.
Use doctor.config.ts only when configuration needs code. Loading executable configuration is an explicit trust decision:
import { defineDoctorConfig } from "vite-doctor/config";
export default defineDoctorConfig({
rules: {
"vite/define/no-secret-define": "error",
},
});
By default extends is auto: the recommended preset of every Rule Pack the project activates. strict selects the strict preset of every activated Rule Pack instead, and keeps the recommended preset of Rule Packs that have no strict preset. Strict presets add noisier, opinionated, and migration-oriented Rules, but not opt-in policy Rules such as typescript/strict/no-comments, which only a rules entry turns on. --strict is short for --extends strict, and "extends": "strict" sets it in doctor.config.json:
{
"extends": "strict"
}
An explicit extends list selects exactly the presets it names and replaces the activated defaults. --extends vite-doctor/typescript/strict runs only the TypeScript strict preset, without the Vite, Vue, Nitro, or Nuxt presets the project activated. Add auto or strict to keep them: --extends auto,vite-doctor/typescript/strict. Passing --strict with --extends adds strict to the list. The CLI, the Vite plugin, and the Nuxt module treat extends the same way. The JSON and agent reports list each Rule Pack once under rulePacks, as { name, selected, activatedBy }: selected says whether extends selected its presets, and activatedBy lists the roots of the workspace packages that activate it (. is the root). Selection does not mean every rule ran: --rules, --analyses, and rule options can still narrow the run. The text report names activated Rule Packs that extends left out.
Config Extends selectors use pack/preset. A selector can use a Rule Pack's full name, such as vendor/vite/recommended, or its short name when that name is unique. If multiple installed packs share a short name, Doctor reports an ambiguity instead of choosing based on registration order; use the full Rule Pack name to select the intended preset.
Duplicate full Rule Pack names are rejected during registration with DOC0023, before preset selection. Distinct full names may share short aliases; using an ambiguous short selector reports DOC0024. An exact full name takes precedence over another pack's short alias.
pnpm dlx vite-doctor . --config doctor.config.ts
When Doctor runs through a host integration, pass the same policy through the plugin surface:
import { doctor } from "vite-doctor";
export default {
plugins: [
doctor({
config: {
include: ["src/**", "vite.config.ts"],
rules: {
"vite/define/no-secret-define": "error",
},
},
}),
],
};
In Vite config, the same plugin covers Vite, Vue, and Nitro projects. Doctor picks the matching diagnostics automatically:
import { doctor } from "vite-doctor";
export default {
plugins: [doctor()],
};
Set framework: "nitro" only when Doctor cannot identify the framework automatically:
import { doctor } from "vite-doctor";
export default {
plugins: [doctor({ framework: "nitro" })],
};
Run in CI/CD
Add a check:doctor script to the project:
{
"scripts": {
"check:doctor": "vite-doctor . --max-warnings 0"
}
}
Don't name the script doctor. pnpm doctor and npm doctor run the package manager's own health check, not your script, so an agent following the obvious command sees a passing check without running Doctor. If the project already has a doctor script, always call it with pnpm run doctor or npm run doctor.
Doctor reads source files, config, and installed packages. It doesn't need build output, so run it before the build as a cheap early check. Nuxt projects that register the vite-doctor/nuxt module also need .nuxt/doctor.manifest.json, which nuxt prepare writes. Most Nuxt projects already run it from a postinstall or prepare script. See Nuxt in CI.
This GitHub Actions example installs dependencies, then runs the package script:
name: Checks
on:
pull_request:
push:
branches: [main]
jobs:
checks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .node-version
- run: corepack enable
- run: pnpm install --frozen-lockfile
- run: pnpm check:doctor
Record existing findings
Record the current Diagnostic fingerprints, then report only findings that are absent from that baseline:
pnpm vite-doctor . --baseline doctor-baseline.json --update-baseline
pnpm vite-doctor . --baseline doctor-baseline.json --new-only
--update-baseline requires an explicit --baseline path and creates missing parent directories. It replaces the recorded set with the findings from the current Doctor Run, so resolved findings disappear from the next baseline. It still reports findings and uses the usual exit codes. When combined with --new-only, the update also retains the currently suppressed fingerprints. Regenerate the baseline with a full run: --changed, --since, and --rules limit the recorded findings to that scope.
Nuxt projects
Nuxt projects should use the module and Nuxt host command:
pnpm add -D vite-doctor
export default defineNuxtConfig({
modules: ["vite-doctor/nuxt"],
doctor: {
rules: {
"nuxt/routing/prefer-nuxt-useroute": "error",
},
},
});
pnpm nuxt doctor
nuxt doctor works locally and in CI; on Nuxt older than 4.6, see
Exit codes. Run nuxt prepare before either command in a fresh checkout.
Use the framework guides when you want setup instructions for one runtime: