Vite

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:

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:

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

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.

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, and plugin HMR behavior. 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.