Nuxt

Nuxt rulesCLI
Install Doctor in a Nuxt project and run Nuxt, Vue, Nitro, and Vite diagnostics from the Nuxt surface.

Use the Nuxt module when the project is a Nuxt app or layer. The module writes Nuxt project inventory for the shared Doctor Run, and vite-doctor provides the Nuxt host-command shim used by nuxt doctor.

Install

The Nuxt Plugin Surface requires Nuxt 4.1.0 or later. Add Vite Doctor to the project:

pnpm add -D vite-doctor

Register the module in nuxt.config.ts:

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

Run Doctor from the project root:

pnpm nuxt doctor

On Nuxt 4.6 and later, nuxt doctor and nuxt doctor migrate preserve Doctor's exit codes, so nuxt doctor --max-warnings 0 can fail a CI job. On Nuxt 4.1 to 4.5, Nuxt's CLI exits 0 whatever Doctor returns, so use the direct CLI in CI there: vite-doctor . --host-extensions --max-warnings 0.

Nuxt handles --help itself, so nuxt doctor --help and nuxt doctor migrate --help show Nuxt's help. To list Doctor's options, use pnpm vite-doctor --help or pnpm vite-doctor migrate --help.

Run in CI

The module writes .nuxt/doctor.manifest.json whenever Nuxt prepares, builds, or starts the dev server. The manifest carries the doctor options from nuxt.config.ts, plus Nuxt's resolved auto-imports, components, layers, and server handlers. The CLI reads that file. It does not load nuxt.config.ts itself. Without the manifest, the run ignores your rule options and suppressions, reports Status: incomplete, and exits with code 3.

Doctor does not need nuxt build or .output. Run it right after nuxt prepare, next to lint and typecheck, instead of after a build or deploy:

package.json
{
  "scripts": {
    "postinstall": "nuxt prepare",
    "check:doctor": "nuxt doctor --max-warnings 0"
  }
}
.github/workflows/ci.yml
- run: pnpm install --frozen-lockfile # runs nuxt prepare through postinstall
- run: pnpm check:doctor
- run: pnpm build

Don't name the script doctor: pnpm doctor and npm doctor run the package manager's built-in health check instead. If a doctor script already exists, call it with pnpm run doctor.

A manifest left behind by nuxt build also records the client build manifest. With it, nuxt/hydration/no-browser-global-in-universal-code reports browser globals in code it cannot classify as errors instead of warnings, so a run after a build can be stricter than a run after nuxt prepare.

Doctor records Nuxt's resolved future.compatibilityVersion and follows the installed Nuxt package to the Nitro and H3 instances that Nuxt actually owns. Compatibility 5 diagnostics can therefore activate on Nuxt 4 while Nitro 2 and H3 v1 rules remain unchanged.

Before upgrading, evaluate the current project against the Nuxt 5 target graph:

pnpm nuxt doctor migrate

The migration report lists source changes that are safe on the installed runtime first, then coupled dependency, configuration, and target-only source changes, followed by checks to run after installation. Pass --to nuxt@5 when inference is unavailable, and add --format json for structured output. Doctor does not rewrite the project.

Configure

Use the top-level doctor key for Nuxt projects. Host config is already trusted by Nuxt, so Doctor can receive in-memory surface configuration without loading a separate executable config file.

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

Nuxt adds types for the doctor key when it prepares the project.

The doctor key takes the same fields as doctor.config.json, including per-path overrides. See Configuration. The module records configuration only; choose what a run reports with the command, such as pnpm nuxt doctor --since origin/main.

Use extends: "auto" to keep Doctor's activated presets. Use extends: "strict" to run the strict preset of every activated Rule Pack instead, the same as pnpm nuxt doctor --strict; Rule Packs without a strict preset keep their recommended preset. Use an explicit array when you need to choose the Nuxt, Vue, and Nitro presets yourself:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ["vite-doctor/nuxt"],
  doctor: {
    extends: ["nuxt/recommended", "vue/recommended", "nitro/recommended"],
  },
});

Optional API authorization review

For projects with custom server guard wrappers, register the Nuxt authorization review Rule Pack through an explicit Doctor config. This review sends auth-sensitive handlers, route middleware, server middleware, and up to four local imports per handler to the model endpoint you configure. Files over 16 KB are skipped, and each request is limited to 120 KB. If any conventional server middleware cannot be collected, Doctor skips authorization review and reports an evidence gap with the affected files. Its report status is incomplete, because the omitted middleware could protect any handler. It reports only when the response cites valid lines in both the handler and related source. Unknown answers produce no diagnostic.

doctor.config.ts
import {
  createNuxtAuthorizationReviewExtension,
  createOpenAICompatibleAuthorizationReviewer,
} from "vite-doctor/rule-packs/nuxt";

export default {
  extends: ["auto", "nuxt-review/recommended"],
  rules: { "nuxt/middleware/no-route-middleware-api-security": "off" },
  extensions: [
    createNuxtAuthorizationReviewExtension(
      createOpenAICompatibleAuthorizationReviewer({
        endpoint: "https://your-provider.example/v1/chat/completions",
        model: "your-review-model",
        apiKey: process.env.REVIEW_API_KEY!,
      }),
    ),
  ],
};

Run the CLI with the executable config explicitly selected:

pnpm vite-doctor . --framework nuxt --config doctor.config.ts

The example disables the built-in NUXT0037 heuristic because it accepts only guards it can follow or that the guards option names. The review evaluates custom wrappers independently; a suppress result does not remove another Rule Pack's diagnostics. A stale Nuxt manifest makes review evidence incomplete until the manifest is regenerated.

The review emits NUXT0074 with low confidence and source citations. Keep server authorization checks in the application even when the review produces no finding.

Rules from Nuxt modules

Nuxt modules can ship their own Rule Packs through the doctor:extendExtensions hook. When the module and vite-doctor/nuxt are both installed, pnpm nuxt doctor runs those Rules with the built-in packs, and their Diagnostic Codes link to the module's own docs. The direct CLI loads the same Rules only when you pass --host-extensions:

pnpm vite-doctor . --host-extensions --max-warnings 0

See Extending Doctor to write Rules for your app or ship them from a module.

Pick the right reference

Nuxt projects run more than one runtime-owned rule pack. Use the diagnostic prefix to decide where to read next:

  • nuxt/... diagnostics are documented in Nuxt rules.
  • vue/... diagnostics are documented in Vue rules.
  • nitro/... diagnostics are documented in Nitro rules.
  • vite/... diagnostics are documented in Vite rules.

Fix a diagnostic

Open the rule page from the reported rule ID. Each page explains why the diagnostic matters, the recommended replacement, and a before/after example.

Run one rule while you fix it:

pnpm nuxt doctor --rules nuxt/hydration/no-time-dependent-render-without-nuxttime-or-clientonly

Use --fix only when the rule says it has an auto-fix. Suggestion rules explain the safer manual edit.

Copyright © 2026