vite-doctor

Vite Doctor

Catch framework bugs AI agents miss. Diagnostics for Nuxt, Vue, Nitro and Vite.

pnpm dlx vite-doctor .

Docs · Comark UI extension

Usage

Run Vite Doctor from the project root:

pnpm dlx vite-doctor .

Vite Doctor reads app code, build config, project metadata, and server handlers to catch framework bugs before review. It resolves the installed Nuxt, Nitro, and H3 runtime graph and picks diagnostics that match the versions the framework actually loads.

Need a narrower Doctor Run? Select exact presets, one Rule, or a framework override:

pnpm dlx vite-doctor . --extends vite/recommended,vue/recommended
pnpm dlx vite-doctor . --rules nuxt/fetch/no-raw-fetch-in-setup
pnpm dlx vite-doctor . --framework nitro

--changed reports Diagnostics owned by staged, unstaged, or untracked lines, exactly as a full run filtered to those lines would. Rules that report only into their own file run on changed files only; Rules that report across files keep whole-project context. Diagnostics without a source range are included when the file they are anchored to changed:

pnpm dlx vite-doctor . --changed
pnpm dlx vite-doctor . --since origin/main

Doctor recognizes coding-agent runtimes through Vercel's agent catalog and returns a compact agent report when output is non-interactive. An explicit format always wins:

pnpm dlx vite-doctor . --format text
pnpm dlx vite-doctor . --format agent
pnpm dlx vite-doctor . --format json
pnpm dlx vite-doctor . --format sarif

Agent reports use relative locations and include remediation, Diagnostic Reference URLs, and command templates for explanation, focused verification, and the full rerun. Automation can execute the commandArgs arrays without a shell; commands provides quoted POSIX templates.

For Nuxt projects, install Vite Doctor and run it through Nuxt:

pnpm add -D vite-doctor
pnpm nuxt doctor

Use --framework only when Doctor cannot identify the framework automatically.

For CI, add a package script and run it before the build. Doctor reads source and config, not build output. Nuxt projects only need nuxt prepare first:

{
  "scripts": {
    "check:doctor": "vite-doctor . --max-warnings 0"
  }
}

Don't name the script doctor. pnpm doctor and npm doctor run the package manager's built-in health check instead of your script.

Check a migration before changing dependencies:

pnpm dlx vite-doctor migrate .
pnpm dlx vite-doctor migrate . --to nuxt@5 --format json
pnpm dlx vite-doctor migrate . --to nitro@3

The migration report stages source changes that are safe on the installed runtime, then dependency, configuration, and source changes that must land together, followed by checks that require the target runtime. It does not rewrite the project.

Configuration

Doctor automatically loads declarative doctor.config.json without executing project code:

{
  "rules": {
    "vite/define/no-secret-define": "error"
  }
}

Executable config remains explicit because loading it runs project code:

// doctor.config.ts
import { defineDoctorConfig } from "vite-doctor/config";

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

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

Plugin surfaces accept the same policy through host config:

// vite.config.ts
import { doctor } from "vite-doctor";

export default {
  plugins: [
    doctor({
      config: {
        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:

// vite.config.ts
import { doctor } from "vite-doctor";

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

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

// vite.config.ts
import { doctor } from "vite-doctor";

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

Use the Nuxt module surface for Nuxt-specific configuration:

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

Removed run options

Remove coverage, runtimeEvidence, emitGraph, confidenceMin, and scoreOnly from DoctorRunOptions objects. These options had no effect on Doctor Runs; their removal is a breaking TypeScript API change. Runtime Evidence contributors, graph reports, diagnostic confidence, and scoring remain supported.

Doctor extensions

Library authors can import createRule, defineRulePack, defineDoctorExtension, and defineDoctorDiagnostics from vite-doctor/extension. The same entrypoint exports their authoring types. Vite plugins attach extensions automatically through api.doctor (DoctorPluginApi), and Nuxt modules use the doctor:extendExtensions hook. Test Rules with runRuleFixture and runProjectFixture from vite-doctor/testkit. See Extending Doctor. Rule Pack names identify the owner of each Config Extends preset and must be unique within a Doctor Run. Shared final slash-delimited segments require full names in Config Extends; registering duplicate full names fails with the internal DOC0023 authoring diagnostic.

comark-linter is a published Doctor Extension: it checks Comark Markdown documents and the plugins from Comark UI. Register comark() from comark-linter/doctor in doctor.config.ts, add comark/recommended to extends, and run with --config.

Development

vp run ready
vp run -r test
vp run -r build

Releasing

See the maintainer release guide for release PRs, npm approval, and recovery steps.