Vite

Vite rulesCLI
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:

pnpm add -D vite-doctor

Register the plugin in vite.config.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:

pnpm vite-doctor . --rules vite

Configure

Use plugin options for build-time behavior:

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.

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:

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:

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 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+ 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:

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,
      },
    },
  },
});
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, so vp run fails when Doctor does. To check everything with one command, chain the task after vp check in a package script:

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:

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,
      },
    },
  },
});
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.

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

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.

Copyright © 2026