fix(prerender): warn and keep first output when two routes collide

[sobol-sudo]

🔗 Linked issue

Resolves the dedup half of #4487. The other half, the non-atomic write, is #4488 — the two are independent and this branch is cut from main, not from that one.

❓ Type of change

• 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Two prerender routes can resolve to a single output file — /other and /other/index.html both become other/index.html under autoSubfolderIndex. Nitro renders both and writes both to that one path, so the file that ships is whichever render happened to finish last, and nothing in the output says a route was discarded.

Nuxt produces exactly this pair without the user asking: it adds a prerender route /index.html alongside the page route / whenever ssr: false, and raises prerender.concurrency above 1.

The resolved fileName is only known after a route has been rendered, so this cannot be deduped when routes are queued. This tracks the file each route resolved to and, when a second route resolves to a file that is already taken, warns and skips the write instead of replacing the first route's output:

WARN  Routes `/other` and `/other/index.html` both prerender to `/other/index.html`. Keeping the output of `/other`.

The skipped route is marked skip, so it already renders as (skipped) in the prerender log through formatPrerenderRoute. The file is claimed synchronously before the write is awaited, so a concurrent render resolving to the same file sees it as taken.

Which of the two routes wins is still the one that finished first, and with concurrency > 1 that is not deterministic. Making it deterministic would mean ordering the writes, which seemed like a bigger change than this warrants — the point here is that the build no longer silently discards a render, and the warning names both routes so the duplicate can be removed from the route list. Happy to go further if you would prefer the winner to be pinned to route order.

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

test/prerender/collision.test.ts builds a small fixture with both routes and asserts the warning fires once, that only one route claims the file, and that the file holds that route's render. It fails on main (no warning, both routes recorded as written) and passes with this change.

Locally: test/unit 174 passed / 2 skipped, tsc --noEmit clean, oxlint and oxfmt --check clean.

[vercel]

@sobol-sudo is attempting to deploy a commit to the Nitro Team on Vercel.

A member of the Team first needs to authorize it.

[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: e47f984b-941c-4824-9c14-83fdd32049f5

📥 Commits

Reviewing files that changed from the base of the PR and between 983d87b and fdc4f3b.

📒 Files selected for processing (2)

• src/prerender/prerender.ts
• test/prerender/collision.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• test/prerender/collision.test.ts

---

📝 Walkthrough

Walkthrough

Changes

Prerender collision handling

Layer / File(s)	Summary
Claim output files before writing src/prerender/prerender.ts	Tracks the first route for each resolved output file, warns and skips later collisions, and claims files before asynchronous writes.
Validate colliding static routes test/prerender/collision.test.ts, test/prerender/fixture/server.ts	Adds static prerender collision coverage, warning assertions, winner verification, generated HTML validation, and temporary-directory cleanup.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• Prerender: two routes resolving to the same output file are neither deduped nor written atomically #4487 — Directly concerns deduplicating prerender routes by resolved output filename and preventing concurrent writes.

Possibly related PRs

• nitrojs/nitro#4488 — Addresses concurrent writes to the same output path through atomic file replacement.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows conventional commits and accurately summarizes the prerender collision fix.
Description check	✅ Passed	The description matches the changeset and explains the collision fix and new test clearly.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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

🛠️ Fix failing CI checks 💡

• Fix failing CI checks

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/prerender/prerender.ts`:
- Around line 114-117: Update the route deduplication map usage in the prerender
flow to key both lookups and insertions by the resolved filePath used for
writing, rather than the raw route.fileName. Ensure the checks and updates
around routeByOutputFile consistently use filePath so filename aliases resolving
to the same output are treated as one target.

In `@test/prerender/collision.test.ts`:
- Around line 20-40: Wrap the Nitro lifecycle operations in the collision test,
including prepare, copyPublicAssets, prerender, and build, in a try/finally
structure, and move nitro.close() into the finally block so it always executes
when setup or prerendering fails. Keep the existing warning capture and
operation order unchanged.
- Around line 42-52: Update the collision assertions in the prerender test to
require that the intended winning route is “/other”, rather than deriving the
expected content from written[0].route. Also verify the collision warning
explicitly names both competing routes, while preserving the existing
single-file assertion.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bb3442a2-7c28-4070-9ee1-57bf1ecdc643

📥 Commits

Reviewing files that changed from the base of the PR and between 77b77ff and 983d87b.

📒 Files selected for processing (3)

• src/prerender/prerender.ts
• test/prerender/collision.test.ts
• test/prerender/fixture/server.ts