fix(analyze,build,dev,preview): server build descriptor with nitro fallback

[danielroe]

🔗 Linked issue

📚 Description

follow-up to #1505 - issue is in nuxt v4.6+, we always write a descriptor, meaning it no longer tells us anything except that nuxt is newer...

so this makes the descriptor a preferred source rather than an exclusive one, respecting nitro-reported values unless it's been overridden...

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 981a2f3b-a8e8-4701-b3d3-14da7d962ada

📥 Commits

Reviewing files that changed from the base of the PR and between 11fc0ab and 76c76ac.

📒 Files selected for processing (3)

• packages/nuxt-cli/src/commands/preview.ts
• packages/nuxt-cli/src/utils/server-build.ts
• packages/nuxt-cli/test/unit/utils/server-build.spec.ts

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The CLI now normalizes declared server builder names by removing the @nuxt/ prefix and -server suffix. Server build resolution falls back to Nitro values when declared target or preview command values are undefined. Unit tests cover normalized names and both fallback cases. Preview always includes .output/public in its static search paths.

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

Merge Risk: ⚪ Minimal · up to 76c76

The change improves server-build metadata resolution by falling back to Nitro values when descriptor fields are missing while preserving explicit overrides. No actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the affected commands and the server build descriptor fallback change.
Description check	✅ Passed	The description explains why the descriptor must be a preferred source and how Nitro fallback should work.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files.
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

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/build-coalesce

---

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.}

[pkg-pr-new]

• nuxt-cli-playground

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

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

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

commit: 76c76ac

[github-actions]

CLI benchmark

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

Metric	baseline v4.0.0-alpha.0	head v4.0.0-alpha.0	Delta
nuxt --version wall time (median)	66 ms	66 ms	-1.0%
nuxt --help wall time (median)	138 ms	138 ms	-0.3%
nuxt dev --help wall time (median)	107 ms	104 ms	-2.6%
nuxt --version modules loaded	38	38	0.0%
nuxt --help modules loaded	138	138	0.0%
nuxt dev --help modules loaded	81	81	0.0%
Installed node_modules	2.38 MB	2.38 MB	+0.0%
Published tarball (packed)	284.6 kB	284.9 kB	+0.1%

Full report

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

Setting	Value
Baseline	ref:11fc0abdd3c0f4dcd4a5cd60ec2885fa662335df (v4.0.0-alpha.0)
Head	local packages/nuxt-cli at efd69c6 (v4.0.0-alpha.0)
Node	v24.19.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	2.11, 0.64, 0.22
Run started	2026-08-31T07:20:19.619Z

Cold CLI startup

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

Command	baseline v4.0.0-alpha.0 median	head v4.0.0-alpha.0 median	Delta	baseline v4.0.0-alpha.0 min / p95	head v4.0.0-alpha.0 min / p95
nuxt --version	66 ms	66 ms	-1.0%	64 ms / 68 ms	64 ms / 69 ms
nuxt --version (first output byte)	62 ms	61 ms	-1.5%	60 ms / 64 ms	60 ms / 65 ms
nuxt --help	138 ms	138 ms	-0.3%	134 ms / 141 ms	135 ms / 141 ms
nuxt --help (first output byte)	133 ms	132 ms	-0.4%	128 ms / 136 ms	129 ms / 135 ms
nuxt dev --help	107 ms	104 ms	-2.6%	104 ms / 118 ms	102 ms / 117 ms
nuxt dev --help (first output byte)	102 ms	99 ms	-2.5%	99 ms / 111 ms	97 ms / 112 ms
nuxt <unknown-command> (no-op)	147 ms	147 ms	+0.3%	144 ms / 150 ms	145 ms / 150 ms
nuxt <unknown-command> (no-op) (first output byte)	140 ms	142 ms	+0.8%	138 ms / 145 ms	139 ms / 144 ms

Module load cost

Counted with a module.registerHooks load hook, compile cache disabled. Counts every JS module actually evaluated on that code path (built-ins excluded, native addons excluded).

Command	baseline v4.0.0-alpha.0 modules	head v4.0.0-alpha.0 modules	Delta	baseline v4.0.0-alpha.0 source bytes	head v4.0.0-alpha.0 source bytes	Delta
nuxt --version	38	38	0.0%	298.7 kB	298.7 kB	0.0%
nuxt --help	138	138	0.0%	1.01 MB	1.01 MB	+0.0%
nuxt dev --help	81	81	0.0%	620.1 kB	620.3 kB	+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.0	head v4.0.0-alpha.0	Delta
Direct dependencies of @nuxt/cli	21	21	0.0%
Packages in the installed tree (unique name@version)	34	34	0.0%
Unique package names	34	34	0.0%
Package directories on disk (cross-check)	28	28	0.0%
Installed node_modules on disk	2.38 MB	2.38 MB	+0.0%
Installed files	419	419	0.0%
Install wall time (warm npm cache, median of 3)	655 ms	654 ms	-0.1%
Published tarball (packed)	284.6 kB	284.9 kB	+0.1%
Published tarball (unpacked)	983.7 kB	983.9 kB	+0.0%
Files in tarball	131	131	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.

[codspeed-hq]

Merging this PR will not alter performance

✅ 2 untouched benchmarks

---

_{Comparing fix/build-coalesce (76c76ac) with main (84e7673)¹}

Footnotes

1. No successful run was found on main (11fc0ab) during the generation of this report, so 84e7673 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩