---
title: "CLI"
description: "Run framework diagnostics from one command."
canonical_url: "https://vite-doctor.onmax.me/cli"
---
# CLI

> Run framework diagnostics from one command.

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

```bash
pnpm dlx vite-doctor .
```

Narrow the Doctor Run when you need changed files, strict CI failure behavior, one Rule, or safe fixes:

```bash
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:

```bash
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.

```bash
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:

1. Stop all Doctor processes sharing the cache, including dev servers using a Plugin Surface and processes in other containers.
2. From the project root, run `pnpm vite-doctor cache clean`. Pass the same `--config` and `--framework` options used by the original run. For a Plugin Surface with an in-memory custom cache directory, use `cleanCache(root, config)` from `vite-doctor` with that configuration after stopping the hosts.
3. 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:

```bash
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
```

<table>
<thead>
  <tr>
    <th>
      Analysis
    </th>
    
    <th>
      Diagnostic Reference
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        graph
      </code>
    </td>
    
    <td>
      <a href="https://vite-doctor.onmax.me/diagnostics/DOC0001">
        DOC0001: circular dependencies
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        graph
      </code>
    </td>
    
    <td>
      <a href="https://vite-doctor.onmax.me/diagnostics/DOC0002">
        DOC0002: repeated export names
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dead-code
      </code>
    </td>
    
    <td>
      <a href="https://vite-doctor.onmax.me/diagnostics/DOC0003">
        DOC0003: undeclared dependencies
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dead-code
      </code>
    </td>
    
    <td>
      <a href="https://vite-doctor.onmax.me/diagnostics/DOC0004">
        DOC0004: unresolved source imports
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dead-code
      </code>
    </td>
    
    <td>
      <a href="https://vite-doctor.onmax.me/diagnostics/DOC0005">
        DOC0005: apparently unused dependencies
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dead-code
      </code>
    </td>
    
    <td>
      <a href="https://vite-doctor.onmax.me/diagnostics/DOC0006">
        DOC0006: unreachable value exports
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dead-code
      </code>
    </td>
    
    <td>
      <a href="https://vite-doctor.onmax.me/diagnostics/DOC0007">
        DOC0007: unreachable source files
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dead-code
      </code>
    </td>
    
    <td>
      <a href="https://vite-doctor.onmax.me/diagnostics/DOC0008">
        DOC0008: unreachable type exports
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dupes
      </code>
    </td>
    
    <td>
      <a href="https://vite-doctor.onmax.me/diagnostics/DOC0009">
        DOC0009: repeated token sequences
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        health
      </code>
    </td>
    
    <td>
      <a href="https://vite-doctor.onmax.me/diagnostics/DOC0010">
        DOC0010: file-level branch complexity
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        health
      </code>
    </td>
    
    <td>
      <a href="https://vite-doctor.onmax.me/diagnostics/DOC0011">
        DOC0011: many static imports
      </a>
    </td>
  </tr>
</tbody>
</table>

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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://vite-doctor.onmax.me/extending) to write and ship Rules.

## Check a migration before upgrading

Use `migrate` to evaluate the current source against the next supported runtime graph:

```bash
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:

```bash
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:

```bash
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`:

```json [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:

```json [doctor.config.json]
{
  "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:

```ts [vite.config.ts]
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+](https://vite-doctor.onmax.me/vite#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:

```ts [doctor.config.ts]
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`:

```json [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.

```bash
pnpm dlx vite-doctor . --config doctor.config.ts
```

When Doctor runs through a host integration, pass the same policy through the plugin surface:

```ts [vite.config.ts]
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:

```ts [vite.config.ts]
import { doctor } from "vite-doctor";

export default {
  plugins: [doctor()],
};
```

Set `framework: "nitro"` only when Doctor cannot identify the framework automatically:

```ts [vite.config.ts]
import { doctor } from "vite-doctor";

export default {
  plugins: [doctor({ framework: "nitro" })],
};
```

## Run in CI/CD

Add a `check:doctor` script to the project:

```json [package.json]
{
  "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](https://vite-doctor.onmax.me/nuxt#run-in-ci).

This GitHub Actions example installs dependencies, then runs the package script:

```yaml
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:

```bash
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:

```bash
pnpm add -D vite-doctor
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ["vite-doctor/nuxt"],
  doctor: {
    rules: {
      "nuxt/routing/prefer-nuxt-useroute": "error",
    },
  },
});
```

```bash
pnpm nuxt doctor
```

`nuxt doctor` works locally and in CI; on Nuxt older than 4.6, see
[Exit codes](#exit-codes). Run `nuxt prepare` before either command in a fresh checkout.

Use the framework guides when you want setup instructions for one runtime:

- [Nuxt](https://vite-doctor.onmax.me/nuxt)
- [Vue](https://vite-doctor.onmax.me/vue)
- [Vite](https://vite-doctor.onmax.me/vite)
- [Nitro](https://vite-doctor.onmax.me/nitro)


## Sitemap

See the full [sitemap](https://vite-doctor.onmax.me/sitemap.md) for all pages.
