---
title: "Vite"
description: "Install Doctor in a Vite project and run Vite diagnostics through the Vite plugin or CLI surface."
canonical_url: "https://vite-doctor.onmax.me/vite"
---
# Vite

> Install Doctor in a Vite project and run Vite diagnostics through the Vite plugin or CLI surface.

Use the Vite plugin when you want Doctor to run as part of the host build. Use the CLI when you want an explicit command for local checks or CI.

## Install

Add Vite Doctor to the project:

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

Register the plugin in `vite.config.ts`:

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

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

Run Doctor directly when you want a focused scan:

```bash
pnpm vite-doctor . --rules vite
```

## Configure

Use plugin options for build-time behavior:

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

export default defineConfig({
  plugins: [
    doctor({
      framework: "vite",
      run: "build",
      mode: "error",
      maxWarnings: 0,
      config: {
        rules: {
          "vite/define/no-secret-define": "error",
        },
      },
    }),
  ],
});
```

`config` takes the same fields as `doctor.config.json`, including per-path `overrides`. See
[Configuration](https://vite-doctor.onmax.me/cli#configuration).

Set `since` to report only Diagnostics on lines changed since the merge base with a Git ref, or
`changed: true` for lines changed against `HEAD`, untracked files included. They work like the
CLI's `--since` and `--changed`: the run still analyzes the whole project, and a Git failure fails
the run instead of reporting nothing:

```ts [vite.config.ts]
doctor({ run: "build", since: "origin/main", maxWarnings: 0 });
```

When a Doctor Run is `incomplete` because required Project Inventory or Runtime Evidence is
missing, `mode: "error"` fails the host build even when the report has no error-level
Diagnostics. Set `mode: "warn"` to keep the build running while the report records the missing
evidence.

With `run: "serve"` or `run: "both"`, the dev server starts without waiting for Doctor. The
Doctor Run begins after the server listens and prints its report through the Vite logger when it
finishes. It runs in a worker thread unless `extensions` or Vite plugins that expose
`api.doctor` add Doctor Extensions, which have to run on the main thread. In `mode: "error"`,
failing Diagnostics are logged as errors; they never stop the dev server. Restarting or closing
the server discards a Doctor Run that has not finished.

After that first report, Doctor batches source saves within 100 ms. The rerun keeps whole-project
context for cross-file Rules. By default, it limits the report update to the saved files, so a
finding elsewhere may not update until that file is saved or the server restarts. With `since`
or `changed`, a save instead refreshes the entire Git-scoped report, including Diagnostics on
Git-changed lines in files you did not save. The log shows what changed since the
previous run: each new Diagnostic in full, each resolved one on one line, and a `Now:` line with
the totals Doctor knows. A save that changes nothing logs nothing. In `mode: "error"`, the log is
an error only when the save added a failing Diagnostic or missing evidence. A save during a
rerun replaces it. Saving a `package.json` refreshes the whole report (still Git-scoped if
configured); other non-source files, such as stylesheets, do not rerun Doctor.

## Configure without the plugin

Doctor needs no config file. When you do want config and already have a `vite.config.ts`, put it under the `doctor` key instead of adding a `doctor.config.json`:

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

export default defineConfig({
  doctor: defineDoctorConfig({
    rules: {
      "vite/define/no-secret-define": "error",
    },
  }),
});
```

The `vite-doctor` CLI reads this key by parsing `vite.config.ts`, without running it, so the value has to be a literal. It looks for `vite.config.*` only in the directory it checks, the one you pass as `vite-doctor <dir>`, not in Vite's `root` option or a parent directory. It doesn't follow imports, so keep the key in `vite.config.*` itself rather than in a shared base config. The `doctor()` plugin uses the same key when you don't pass it `config`. Doctor Extensions and computed values can't be read without running code: pass them to `doctor()`, or to a `doctor.config.ts` loaded with `--config`. See [Configuration](https://vite-doctor.onmax.me/cli#configuration) for the exact rules.

The key type-checks with `defineConfig()` from `vite`, `vitest/config`, and `vite-plus` when the TypeScript program imports `vite-doctor` or `vite-doctor/plugin`. Importing only `vite-doctor/config` does not add the key to Vite's types. Vite+ types its `defineConfig()` against its own copy of Vite, so with `vite-plus` the key only type-checks when your `vite` dependency resolves to `@voidzero-dev/vite-plus-core`, for example through a `vite: "npm:@voidzero-dev/vite-plus-core@<version>"` override. When the project also installs Vite itself, as a Nuxt app does, TypeScript reports `doctor` as an unknown property (TS2353): no package can extend the copy of Vite that only lives inside `vite-plus`. The CLI still reads the key. To keep type checks clean there, use `doctor.config.json` instead.

## Run Doctor with Vite+

[Vite+](https://viteplus.dev) has no hook for third-party checkers. `vp check` runs its formatter, linter, and type checks, and the `check` block in `vite.config.ts` only turns those steps on or off. What Vite+ does offer is tasks: `run.tasks` in `vite.config.ts` defines commands that `vp run <task>` executes, and `vp run` exits with the task's exit code. Declare Doctor's config and its task in the same file:

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

export default defineConfig({
  // Optional. Leave it out to run Doctor's defaults.
  doctor: defineDoctorConfig({
    rules: {
      "vite/define/no-secret-define": "error",
    },
  }),
  run: {
    tasks: {
      "check:doctor": {
        command: "vite-doctor . --max-warnings 0",
        cache: false,
      },
    },
  },
});
```

```bash
vp run check:doctor
```

`cache: false` makes every `vp run check:doctor` run Doctor, which keeps its own analysis cache, instead of replaying a stored report. The command exits with Doctor's [exit code](https://vite-doctor.onmax.me/cli#exit-codes), so `vp run` fails when Doctor does. To check everything with one command, chain the task after `vp check` in a package script:

```json [package.json]
{
  "scripts": {
    "check": "vp check && vp run check:doctor"
  }
}
```

Name the task `check:doctor`, not `doctor`: `pnpm doctor` and `npm doctor` run the package manager's own health check.

### Nuxt module repositories

A Nuxt module repository keeps the module at the root and a test app in `playground/`. Nuxt reads `playground/nuxt.config.ts` and never loads the root `vite.config.ts`, but Vite+ and the `vite-doctor` CLI both read the root file, so the `doctor` key and the task belong there. As in any Nuxt project, run `nuxt prepare` before Doctor, here through the module's prepare script:

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

export default defineConfig({
  run: {
    tasks: {
      "check:doctor": {
        command: "vite-doctor . --max-warnings 0",
        dependsOn: ["dev:prepare"],
        cache: false,
      },
    },
  },
});
```

```json [package.json]
{
  "scripts": {
    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
    "check": "vp check && vp run check:doctor"
  }
}
```

## Rules from Vite plugins

Vite plugins can expose Doctor Extensions as `api.doctor`. The Doctor plugin picks them up from the resolved Vite config, so installing a plugin that ships Doctor Rules is enough. Pass `extensions` to `doctor()` for Rules that live in your project. See [Extending Doctor](https://vite-doctor.onmax.me/extending).

## Pick the right reference

Vite rules cover env exposure, `define` replacement, server-only imports, SSR boundaries, assets, workers, plugin HMR behavior, arrays returned from plugin config hooks, Set-Cookie handling in dev server response bridges, `#` in virtual module ids the browser loads, and file paths built from `import.meta.url` in config and plugin code. Start in [Vite rules](https://vite-doctor.onmax.me/vite/rules) when a diagnostic begins with `vite/`.

If the app also uses Vue, Nuxt, or Nitro, use the framework-specific pages for those diagnostic prefixes.

## Fix a diagnostic

Open the rule page from the reported rule ID, make the smallest framework-safe edit, and re-run that one rule:

```bash
pnpm vite-doctor . --framework vite --rules vite/define/no-secret-define
```

Doctor returns compact structured output automatically in recognized agent runtimes. Use `--format agent` for a fixed agent contract or `--format json` for the complete machine report.

---

- [Vite rules](https://vite-doctor.onmax.me/vite/rules)
- [CLI](https://vite-doctor.onmax.me/cli)


## Sitemap

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