perf: print --version without loading the command graph

[productdevbook]

nuxt --version imported dist/index.mjs (citty, every command stub, consola, clack) only to print the version from package.json. This answers it in bin/nuxi.mjs before that import, using citty's own rule: --version or -v as the only argument. Any other argument list (--version extra, dev --version, --profile --version) still goes through citty unchanged.

Benchmark

pnpm bench:cli --baseline ref:origin/main --fixture playground --suite startup --suite modules --startup-reps 21, run on an M3 Max with Node 24.21 and interleaved runs. The baseline is main at f140924.

nuxt --version	main	this PR	Delta
median	45 ms	29 ms	-35.0%
modules evaluated	35	5	-85.7%
source bytes	297.8 kB	5.3 kB	-98.2%
built-ins	27	1	-96.3%

--help, dev --help and unknown commands load the same modules as before (134 / 63). Their timings stay within ±4%, which is run-to-run noise.

Checks

• eslint packages/nuxt-cli/bin/nuxi.mjs passes
• vitest run on compile-cache, dev-boot, startup-checks and e2e/commands passes: 33 passed, 10 todo
• --version and -v print 4.0.0-alpha.1, and --version extra still shows usage

🤖 Generated with Claude Code

[pkg-pr-new]

• nuxt-cli-playground

  npm i https://pkg.pr.new/create-nuxt@1590
  

  npm i https://pkg.pr.new/nuxi@1590
  

  npm i https://pkg.pr.new/@nuxt/cli@1590
  

commit: 1be1b31

[github-actions]

CLI benchmark

@nuxt/cli v4.0.0-alpha.1 (baseline) vs v4.0.0-alpha.1 (this PR)

Metric	baseline v4.0.0-alpha.1	head v4.0.0-alpha.1	Delta
nuxt --version wall time (median)	54 ms	29 ms	-47.3%
nuxt --help wall time (median)	106 ms	108 ms	+1.1%
nuxt dev --help wall time (median)	83 ms	83 ms	-0.3%
nuxt --version modules loaded	35	5	-85.7%
nuxt --version built-ins loaded	27	1	-96.3%
nuxt --help modules loaded	134	134	0.0%
nuxt --help built-ins loaded	87	87	0.0%
nuxt dev --help modules loaded	63	63	0.0%
nuxt dev --help built-ins loaded	87	87	0.0%
Installed node_modules	2.43 MB	2.43 MB	+0.0%
Published tarball (packed)	239.6 kB	239.7 kB	+0.1%

Full report

@nuxt/cli v4.0.0-alpha.1 (baseline) vs v4.0.0-alpha.1 (head)

Setting	Value
Baseline	ref:f140924fb88992febb831316ac01bce275609336 (v4.0.0-alpha.1)
Head	local packages/nuxt-cli at d85c768 (v4.0.0-alpha.1)
Node	v24.21.0
OS	Linux 6.17.0 (kernel 6.17.0-1022-azure)
CPU	AMD EPYC 9V74 80-Core Processor x 4
Memory	15.6 GB
Load average at start	0.72, 0.22, 0.08
Run started	2026-10-03T16:49:50.001Z

Cold CLI startup

Median of 15 interleaved runs per command, one warmup discarded.

Command	baseline v4.0.0-alpha.1 median	head v4.0.0-alpha.1 median	Delta	baseline v4.0.0-alpha.1 min / p95	head v4.0.0-alpha.1 min / p95
nuxt --version	54 ms	29 ms	-47.3%	51 ms / 56 ms	26 ms / 32 ms
nuxt --version (first output byte)	51 ms	26 ms	-49.1%	48 ms / 52 ms	24 ms / 29 ms
nuxt --help	106 ms	108 ms	+1.1%	102 ms / 164 ms	104 ms / 111 ms
nuxt --help (first output byte)	102 ms	103 ms	+1.2%	98 ms / 160 ms	100 ms / 106 ms
nuxt dev --help	83 ms	83 ms	-0.3%	78 ms / 86 ms	80 ms / 85 ms
nuxt dev --help (first output byte)	78 ms	79 ms	+0.4%	74 ms / 82 ms	76 ms / 81 ms
nuxt <unknown-command> (no-op)	116 ms	116 ms	+0.1%	113 ms / 135 ms	114 ms / 119 ms
nuxt <unknown-command> (no-op) (first output byte)	111 ms	111 ms	-0.1%	107 ms / 115 ms	109 ms / 114 ms

Module load cost

Counted with a module.registerHooks load hook, compile cache disabled. Counts every JS module actually evaluated on that code path (native addons excluded). Built-ins loaded after bootstrap are counted separately, including the internal modules they load.

Command	baseline v4.0.0-alpha.1 modules	head v4.0.0-alpha.1 modules	Delta	baseline v4.0.0-alpha.1 source bytes	head v4.0.0-alpha.1 source bytes	Delta	baseline v4.0.0-alpha.1 built-ins	head v4.0.0-alpha.1 built-ins	Delta
nuxt --version	35	5	-85.7%	297.8 kB	5.3 kB	-98.2%	27	1	-96.3%
nuxt --help	134	134	0.0%	839.9 kB	840.3 kB	+0.0%	87	87	0.0%
nuxt dev --help	63	63	0.0%	453.0 kB	453.3 kB	+0.1%	87	87	0.0%

Install footprint and published tarball

Each version installed on its own into an empty project with nothing but @nuxt/cli as a dependency, so the tree is exactly the CLI and its transitive dependencies. npm cache is warm and the registry is only consulted for metadata, so install wall time is indicative, not a network benchmark.

Metric	baseline v4.0.0-alpha.1	head v4.0.0-alpha.1	Delta
Direct dependencies of @nuxt/cli	23	23	0.0%
Packages in the installed tree (unique name@version)	39	39	0.0%
Unique package names	39	39	0.0%
Package directories on disk (cross-check)	32	32	0.0%
Installed node_modules on disk	2.43 MB	2.43 MB	+0.0%
Installed files	434	434	0.0%
Install wall time (warm npm cache, median of 3)	981 ms	976 ms	-0.5%
Published tarball (packed)	239.6 kB	239.7 kB	+0.1%
Published tarball (unpacked)	775.2 kB	775.5 kB	+0.0%
Files in tarball	99	99	0.0%

Interleaved runs on a shared runner: trust the deltas, not the absolute timings. The dev, restart and build suites run locally via pnpm bench:cli.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@f140924). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1590   +/-   ##
=======================================
  Coverage        ?   83.39%           
=======================================
  Files           ?      177           
  Lines           ?    11306           
  Branches        ?     3246           
=======================================
  Hits            ?     9429           
  Misses          ?     1581           
  Partials        ?      296           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[codspeed]

Merging this PR will not alter performance

✅ 2 untouched benchmarks

---

_{Comparing productdevbook:perf/version-fast-path-upstream (1be1b31) with main (f140924)}

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: bea93b7d-b017-49c8-a5d5-2ce2ad81f57b

📥 Commits

Reviewing files that changed from the base of the PR and between f140924 and 1be1b31.

📒 Files selected for processing (1)

• packages/nuxt-cli/bin/nuxi.mjs

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

---

📝 Walkthrough

Walkthrough

When the only argument is --version or -v, the CLI prints the package version without importing or calling runMain(). For other argument lists, it imports and calls runMain().

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~5 minutes

Merge Risk: ⚪ Minimal · up to 1be1b

The version-only shortcut preserves the existing CLI output, while other invocations retain the command-runner path. No actionable merge-blocking risk remains.

Architecture Summary

Architecture risk: 🔵 Low · up to 1be1b

The change affects 1 system.

Changed systems: packages/nuxt-cli

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — packages/nuxt-cli (library) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in packages/nuxt-cli/bin/nuxi.mjs: When the only argument is --version or -v, the script prints the package version and skips importing or calling runMain(). For any other argument list, it imports runMain and calls it.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the version fast path and its goal of avoiding command-graph loading.
Description check	✅ Passed	The description explains the version fast path, its argument behavior, benchmark results, and reported checks.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🧪 Generate unit tests (beta)

• Create a new PR

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}