@geoql/nuxt-doctor

CLI auditor for Nuxt 4 apps. Detects anti-patterns, AI-slop, and best-practice violations via @vue/compiler-sfc + oxlint. Run with `npx -y @geoql/nuxt-doctor`.
14,295 7
nuxt cli nuxt4 doctor lint oxlint geoql audit
Install
npm install @geoql/nuxt-doctor
Latest Version:1.8.2
License:MIT
Last Updated:Sep 18, 2026
Links: GitHub  ·  npm
Maintainer: vinayakkulkarni

@geoql/nuxt-doctor

Your agent writes bad Nuxt. This catches it.

CLI auditor for Nuxt 4 apps. It runs the same hybrid scan as @geoql/vue-doctor — a template-AST pass over @vue/compiler-sfc plus a script pass through oxlint — and layers Nuxt-specific checks (hydration, server routes, Nitro, SEO, Cloudflare, data-fetching) on top, then merges everything into a deterministic 0–100 score. Built for catching the SSR and auto-import mistakes coding agents leave behind.

Install

# one-off, no install
npx -y @geoql/nuxt-doctor

# or add it
npm i @geoql/nuxt-doctor

Published on npm and JSR with provenance.

Usage

nuxt-doctor [path] [options]

path defaults to the current directory. The default output format is agent (compact, built for LLM consumption), not a verbose human report.

# Audit the project and print the agent report
nuxt-doctor

# Human-readable output, fail the build on warnings
nuxt-doctor --format pretty --fail-on warn

# Machine-readable, only staged files, write to a file
nuxt-doctor --json --staged --output report.json

# Just the score, for piping into a gate
nuxt-doctor --score

Options

Flag Description
--format <kind> Output format: agent (default), pretty, json, json-compact, sarif, html.
--json Shorthand for --format json.
--json-compact Single-line JSON.
--config <path> Path to doctor.config.ts.
--preset <name> Base preset: minimal, recommended, strict, all.
--fail-on <level> Exit non-zero at this severity or worse: error (default), warn, none.
--quiet Only show the summary.
--verbose Emit per-pass timing and rule diagnostics to stderr.
--no-color Disable colored output.
--rule <id:level> Override one rule, repeatable. Levels: error, warn, info, off. e.g. --rule nuxt-doctor/seo/lang-on-html:off.
--include <glob> Glob of files to include, repeatable.
--exclude <glob> Glob of files to exclude, repeatable.
--no-dead-code Skip the dead-code (knip) analysis pass.
--no-lint Skip the lint passes (template / SFC / oxlint).
--no-respect-inline-disables Surface findings even inside doctor-disable comments.
--threshold <n> Minimum passing score, integer 0–100.
--score Print only the numeric score, for piping.
--push After the audit, POST privacy-stripped findings to the SaaS. Requires --api-key. Negatable with --no-push.
--no-push Skip the SaaS push (default).
--push-url <url> SaaS endpoint for --push (default: https://app.the-doctor.report/api/v1/findings).
--api-key <key> API key for the SaaS, sent as the x-api-key header.
--annotations Emit GitHub Actions ::error:: / ::warning:: lines.
--ci Auto-enable CI behavior (annotations on GitHub Actions).
--no-ci Disable CI auto-detection even when a CI env is set.
--diff Only report findings in files changed vs HEAD.
--staged Only report findings in staged files.
--full Force a complete scan, overriding --diff / --staged.
--output <file> Write the report to a file instead of stdout.

Severity is error | warn | info everywhere. --diff/--staged, --verbose/--quiet, and --score/--json are mutually exclusive.

Subcommands

Command Description
list-rules List every registered rule with id, severity, category, source, and preset membership. Filters: --preset <recommended|all>, --category <name>, --source <doctor|oxlint-builtin|eslint-plugin-vue>, --severity <error|warn|info>, --json, --json-compact.
explain <ruleId> Print a rule's severity, category, recommendation, and help URL. --json for structured output.
inspect [dir] Print the detected project capabilities doctor uses to gate rules. --json / --json-compact. 
nuxt-doctor list-rules --category hydration
nuxt-doctor explain nuxt-doctor/nitro/compatibilityDate-set
nuxt-doctor inspect --json

Exit codes

Code Meaning
0 Clean, or score at/above --threshold and no findings at/above --fail-on.
1 Findings at/above the --fail-on level (default: error), or score below --threshold.
2 Configuration error or scan failure.

Rules

nuxt-doctor ships ~26 Nuxt rules on top of the full Vue rule set, 59 rules in the registry total. Nuxt categories: structure, nitro, seo, cloudflare, server-routes, hydration, data-fetching, modules-deps, and Nuxt ai-slop; the inherited Vue categories are ai-slop, reactivity, composition, performance, template, template-perf, build-quality, deps, sfc, and dead-code. Run nuxt-doctor list-rules for the live list. Most are on in the recommended preset.

Scope

Nuxt 4 only: the app/ directory layout with compatibilityVersion: 4. For a plain Vue 3 project, use @geoql/vue-doctor.

Architecture

See docs/SPEC.md §10.

License

MIT © Vinayak Kulkarni

Related Packages

@geoql/doctor-core

Audit engine for @geoql/vue-doctor and @geoql/nuxt-doctor. Hybrid two-pass: @vue...

15,374 7
audit doctor geoql lint nuxt oxlint vue vue3
@geoql/vue-doctor

CLI auditor for Vue 3 apps. Detects anti-patterns, AI-slop, and best-practice vi...

4,941 7
audit cli doctor geoql lint oxlint vue vue3
@geoql/oxlint-plugin-nuxt-doctor

oxlint JS plugin for Nuxt 4 anti-patterns and AI-slop detection. Pairs with oxli...

21,363 7
geoql lint nuxt nuxt4 oxlint ai-slop oxlint-plugin
ranklint

Lint your SEO before Google does. Alias for @ranklint/cli: the SEO linter for CI...

1,671 2
audit cli lint nuxt seo
@geoql/doctor-language-server

LSP server that runs the @geoql/doctor audit engine over Vue 3 + Nuxt 4 files an...

2,578 7
audit doctor geoql lint nuxt language-server lsp vue vue3

Version History

Version Released License
1.8.2 MIT
1.8.1 MIT
1.8.0 MIT
1.7.0 MIT
1.6.0 MIT
Pre-releases (1)
Version Released License
0.0.0-bootstrap MIT