feat(nuxi): add nuxt doctor diagnostic command

Hook-based diagnostic command. Core checks built-in, modules contribute via `doctor:check` hook.

- Validates config against common misconfigurations
- Checks Node/Nuxt version compatibility
- Detects module compatibility issues
- Supports --verbose and --json flags
- Graceful hook error handling

Author: onmax

packages/nuxi/src/commands/_utils.ts

@@ -10,6 +10,7 @@ export const nuxiCommands = [
   '_dev',
   'dev',
   'devtools',
+  'doctor',
   'generate',
   'info',
   'init',

packages/nuxi/src/commands/doctor.ts

@@ -0,0 +1,341 @@
+import type { Nuxt } from '@nuxt/schema'
+
+import process from 'node:process'
+
+import { intro, log, outro } from '@clack/prompts'
+import { defineCommand } from 'citty'
+import { colors } from 'consola/utils'
+import { resolve } from 'pathe'
+import { readPackageJSON } from 'pkg-types'
+import { satisfies as semverSatisfies } from 'semver'
+import { isBun, isDeno } from 'std-env'
+
+import { loadKit, tryResolveNuxt } from '../utils/kit'
+import { cwdArgs, dotEnvArgs, extendsArgs, legacyRootDirArgs, logLevelArgs } from './_shared'
+
+// Types for the hook-based architecture (will move to @nuxt/schema)
+interface DoctorCheck {
+  // Required
+  name: string
+  status: 'success' | 'warning' | 'error'
+  message: string
+
+  // Optional - identity/origin
+  id?: string // programmatic code: "MISSING_PEER_DEP"
+  source?: string // module name: "@nuxt/ui"
+
+  // Optional - verbose fields
+  details?: string | string[]
+  suggestion?: string
+  url?: string
+
+  // Optional - programmatic
+  data?: Record<string, unknown>
+}
+
+interface DoctorCheckContext {
+  addCheck: (check: DoctorCheck) => void
+  nuxt: Nuxt
+}
+
+// Augment NuxtHooks for the doctor:check hook (will be moved to @nuxt/schema)
+declare module '@nuxt/schema' {
+  interface NuxtHooks {
+    'doctor:check': (ctx: DoctorCheckContext) => void | Promise<void>
+  }
+}
+
+async function resolveNuxtVersion(cwd: string): Promise<string | undefined> {
+  const nuxtPath = tryResolveNuxt(cwd)
+  for (const pkg of ['nuxt', 'nuxt-nightly', 'nuxt-edge', 'nuxt3']) {
+    const pkgJson = await readPackageJSON(pkg, { url: nuxtPath || cwd }).catch(() => null)
+    if (pkgJson?.version) {
+      return pkgJson.version
+    }
+  }
+}
+
+export default defineCommand({
+  meta: {
+    name: 'doctor',
+    description: 'Run diagnostic checks on Nuxt project',
+  },
+  args: {
+    ...cwdArgs,
+    ...legacyRootDirArgs,
+    ...logLevelArgs,
+    ...dotEnvArgs,
+    ...extendsArgs,
+    verbose: {
+      type: 'boolean',
+      description: 'Show details, suggestions, and URLs',
+    },
+    json: {
+      type: 'boolean',
+      description: 'Output results as JSON',
+    },
+  },
+  async run(ctx) {
+    const cwd = resolve(ctx.args.cwd || ctx.args.rootDir)
+    const isJson = ctx.args.json
+
+    if (!isJson) {
+      intro(colors.cyan('Running diagnostics...'))
+    }
+
+    const { loadNuxt } = await loadKit(cwd)
+
+    let nuxt: Nuxt
+    try {
+      nuxt = await loadNuxt({
+        cwd,
+        ready: true,
+        overrides: {
+          logLevel: ctx.args.logLevel as 'silent' | 'info' | 'verbose' | undefined,
+        },
+      })
+    }
+    catch (err) {
+      if (isJson) {
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify([{ name: 'Setup', status: 'error', message: `Failed to load Nuxt: ${err instanceof Error ? err.message : String(err)}` }]))
+      }
+      else {
+        log.error(colors.red(`Failed to load Nuxt: ${err instanceof Error ? err.message : String(err)}`))
+        outro(colors.red('Diagnostics failed'))
+      }
+      process.exit(1)
+      return // unreachable but needed for type narrowing in tests
+    }
+
+    const checks: DoctorCheck[] = []
+
+    try {
+      // 1. Run built-in checks
+      await runCoreChecks(checks, nuxt, cwd)
+
+      // 2. Let modules contribute via hook (catch errors to preserve partial results)
+      try {
+        await nuxt.callHook('doctor:check', {
+          addCheck: (c: DoctorCheck) => checks.push(c),
+          nuxt,
+        })
+      }
+      catch (err) {
+        checks.push({
+          id: 'HOOK_ERROR',
+          name: 'Module Checks',
+          status: 'error',
+          message: `Hook failed: ${err instanceof Error ? err.message : String(err)}`,
+        })
+      }
+
+      // 3. Display results
+      displayResults(checks, { verbose: ctx.args.verbose, json: isJson })
+    }
+    finally {
+      await nuxt.close()
+    }
+
+    const hasErrors = checks.some(c => c.status === 'error')
+    const hasWarnings = checks.some(c => c.status === 'warning')
+
+    if (!isJson) {
+      if (hasErrors) {
+        outro(colors.red('Diagnostics complete with errors'))
+      }
+      else if (hasWarnings) {
+        outro(colors.yellow('Diagnostics complete with warnings'))
+      }
+      else {
+        outro(colors.green('All checks passed!'))
+      }
+    }
+
+    if (hasErrors) {
+      process.exit(1)
+    }
+  },
+})
+
+async function runCoreChecks(checks: DoctorCheck[], nuxt: Nuxt, cwd: string): Promise<void> {
+  // Version check
+  await checkVersions(checks, cwd)
+
+  // Config validation
+  checkConfig(checks, nuxt)
+
+  // Module compatibility
+  await checkModuleCompat(checks, nuxt, cwd)
+}
+
+async function checkVersions(checks: DoctorCheck[], cwd: string): Promise<void> {
+  const runtime = isBun
+    // @ts-expect-error Bun global
+    ? `Bun ${Bun?.version}`
+    : isDeno
+      // @ts-expect-error Deno global
+      ? `Deno ${Deno?.version.deno}`
+      : `Node ${process.version}`
+
+  const nuxtVersion = await resolveNuxtVersion(cwd) ?? 'unknown'
+
+  // Check Node.js version (if not Bun/Deno)
+  if (!isBun && !isDeno) {
+    const nodeVersion = process.version
+    const major = Number.parseInt(nodeVersion.slice(1).split('.')[0] || '0', 10)
+
+    if (major < 18) {
+      checks.push({
+        id: 'UNSUPPORTED_NODE',
+        name: 'Versions',
+        status: 'error',
+        message: `${runtime}, Nuxt ${nuxtVersion} - Node.js 18+ required`,
+        suggestion: 'Upgrade Node.js to v18 or later',
+        url: 'https://nuxt.com/docs/getting-started/installation#prerequisites',
+      })
+      return
+    }
+  }
+
+  checks.push({
+    name: 'Versions',
+    status: 'success',
+    message: `${runtime}, Nuxt ${nuxtVersion}`,
+  })
+}
+
+function checkConfig(checks: DoctorCheck[], nuxt: Nuxt): void {
+  const issues: string[] = []
+
+  // Check for common misconfigurations
+  if (nuxt.options.ssr === false && nuxt.options.nitro?.prerender?.routes?.length) {
+    issues.push('prerender routes defined but SSR is disabled')
+  }
+
+  // Check for deprecated options
+  if ((nuxt.options as any).target) {
+    issues.push('deprecated "target" option - use ssr + nitro.preset instead')
+  }
+
+  if ((nuxt.options as any).mode) {
+    issues.push('deprecated "mode" option - use ssr: true/false instead')
+  }
+
+  // Check for missing compatibilityDate
+  if (!nuxt.options.compatibilityDate) {
+    issues.push('missing "compatibilityDate" - add to nuxt.config.ts for future compat')
+  }
+
+  if (issues.length > 0) {
+    checks.push({
+      id: 'CONFIG_ISSUES',
+      name: 'Config',
+      status: 'warning',
+      message: `${issues.length} issue${issues.length > 1 ? 's' : ''} found`,
+      details: issues,
+      suggestion: 'Review nuxt.config.ts and fix the issues above',
+      url: 'https://nuxt.com/docs/getting-started/configuration',
+    })
+  }
+  else {
+    checks.push({
+      name: 'Config',
+      status: 'success',
+      message: 'no issues',
+    })
+  }
+}
+
+async function checkModuleCompat(checks: DoctorCheck[], nuxt: Nuxt, cwd: string): Promise<void> {
+  const nuxtVersion = await resolveNuxtVersion(cwd)
+  if (!nuxtVersion) {
+    return
+  }
+
+  const installedModules: { meta?: { name?: string, version?: string, compatibility?: { nuxt?: string } } }[] = (nuxt.options as any)._installedModules || []
+  const moduleDetails: string[] = []
+  const issues: string[] = []
+
+  for (const mod of installedModules) {
+    if (!mod.meta?.name)
+      continue
+
+    const name = mod.meta.name
+    const version = mod.meta.version ? `@${mod.meta.version}` : ''
+    const compat = mod.meta.compatibility
+
+    if (compat?.nuxt && !semverSatisfies(nuxtVersion, compat.nuxt, { includePrerelease: true })) {
+      issues.push(`${name}${version} - requires nuxt ${compat.nuxt}`)
+    }
+    else {
+      moduleDetails.push(`${name}${version}`)
+    }
+  }
+
+  if (issues.length > 0) {
+    checks.push({
+      id: 'MODULE_COMPAT',
+      name: 'Modules',
+      status: 'warning',
+      message: `${issues.length} incompatible module${issues.length > 1 ? 's' : ''}`,
+      details: issues,
+      suggestion: 'Update modules to versions compatible with your Nuxt version',
+      url: 'https://nuxt.com/modules',
+    })
+  }
+  else if (moduleDetails.length > 0) {
+    checks.push({
+      name: 'Modules',
+      status: 'success',
+      message: `${moduleDetails.length} module${moduleDetails.length > 1 ? 's' : ''} loaded`,
+      details: moduleDetails,
+    })
+  }
+  else {
+    checks.push({
+      name: 'Modules',
+      status: 'success',
+      message: 'no modules installed',
+    })
+  }
+}
+
+function displayResults(checks: DoctorCheck[], opts: { verbose?: boolean, json?: boolean }): void {
+  if (opts.json) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(checks))
+    return
+  }
+
+  for (const check of checks) {
+    const icon = check.status === 'success' ? colors.green('✓') : check.status === 'warning' ? colors.yellow('!') : colors.red('✗')
+    const source = check.source ? colors.gray(` (via ${check.source})`) : ''
+    const name = colors.bold(check.name)
+    const message = check.status === 'error' ? colors.red(check.message) : check.status === 'warning' ? colors.yellow(check.message) : check.message
+
+    // Build output with details on same block
+    let output = `[${icon}] ${name}${source} - ${message}`
+
+    // Show details array
+    const details = check.details ? (Array.isArray(check.details) ? check.details : [check.details]) : []
+    if (details.length) {
+      const detailColor = check.status === 'error' ? colors.red : check.status === 'warning' ? colors.yellow : colors.dim
+      for (const detail of details) {
+        output += `\n    ${detailColor('→')} ${detailColor(detail)}`
+      }
+    }
+
+    // Verbose: show suggestion and url
+    if (opts.verbose) {
+      if (check.suggestion) {
+        output += `\n    ${colors.cyan('💡')} ${colors.cyan(check.suggestion)}`
+      }
+      if (check.url) {
+        output += `\n    ${colors.blue('🔗')} ${colors.blue(check.url)}`
+      }
+    }
+
+    log.message(output)
+  }
+}

packages/nuxi/src/commands/index.ts

@@ -8,6 +8,7 @@ export const commands = {
   'analyze': () => import('./analyze').then(_rDefault),
   'build': () => import('./build').then(_rDefault),
   'cleanup': () => import('./cleanup').then(_rDefault),
+  'doctor': () => import('./doctor').then(_rDefault),
   '_dev': () => import('./dev-child').then(_rDefault),
   'dev': () => import('./dev').then(_rDefault),
   'devtools': () => import('./devtools').then(_rDefault),