---
title: "Nuxt"
description: "Install Doctor in a Nuxt project and run Nuxt, Vue, Nitro, and Vite diagnostics from the Nuxt surface."
canonical_url: "https://vite-doctor.onmax.me/nuxt"
---
# Nuxt

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

```bash
pnpm add -D vite-doctor
```

Register the module in `nuxt.config.ts`:

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

Run Doctor from the project root:

```bash
pnpm nuxt doctor
```

On Nuxt 4.6 and later, `nuxt doctor` and `nuxt doctor migrate` preserve Doctor's [exit codes](https://vite-doctor.onmax.me/cli#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:

```json [package.json]
{
  "scripts": {
    "postinstall": "nuxt prepare",
    "check:doctor": "nuxt doctor --max-warnings 0"
  }
}
```

```yaml [.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:

```bash
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.

```ts [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](https://vite-doctor.onmax.me/cli#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:

```ts [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.

```ts [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:

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

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

See [Extending Doctor](https://vite-doctor.onmax.me/extending) 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](https://vite-doctor.onmax.me/nuxt/rules).
- `vue/...` diagnostics are documented in [Vue rules](https://vite-doctor.onmax.me/vue/rules).
- `nitro/...` diagnostics are documented in [Nitro rules](https://vite-doctor.onmax.me/nitro/rules).
- `vite/...` diagnostics are documented in [Vite rules](https://vite-doctor.onmax.me/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:

```bash
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.

---

- [Nuxt rules](https://vite-doctor.onmax.me/nuxt/rules)
- [CLI](https://vite-doctor.onmax.me/cli)


## Sitemap

See the full [sitemap](https://vite-doctor.onmax.me/sitemap.md) for all pages.
