Nuxt

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:

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

Run Doctor from the project root:

pnpm nuxt doctor

The Nuxt host command prints the same Doctor report, but Nuxt currently can swallow the shim's nonzero exit status. Use the direct CLI for CI checks that must fail on Diagnostics or warning thresholds:

pnpm vite-doctor . --max-warnings 0
pnpm vite-doctor migrate . --to nuxt@5 --format json

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.

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.

Use extends: "auto" to keep Doctor's activated presets. Use an explicit array when you need to choose the Nuxt, Vue, and Nitro presets yourself:

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.

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 recognizes only known guard 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. In CI, pass --host-extensions to the direct CLI so it loads the same Rules:

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.