docs: clarify prerender and isr route rules

[vittorioexp]

Summary

Closes #4041.

Documents that prerender and isr must not be combined on the same route — prerendered pages are generated at build time and ISR is ignored. Adds routing guide warnings and updates the isr JSDoc.

Test plan

• Docs-only change (plus JSDoc)
• Wording aligned with maintainer clarification on the issue

[vercel]

@vittorioexp is attempting to deploy a commit to the Nitro Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

The routing documentation now distinguishes build-time prerendering from on-demand ISR. The isr route-rule JSDoc also states that ISR must not be combined with prerender.

Changes

Routing behavior documentation

Layer / File(s)	Summary
Prerender behavior docs/1.docs/5.routing.md	Documents that prerendered routes are generated once during the build and served without runtime revalidation.
ISR exclusivity and revalidation docs/1.docs/5.routing.md, src/types/route-rules.ts	Explains on-demand ISR generation and expiration-based revalidation, and states that isr is ignored when prerender is enabled on the same route.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

• nitrojs/nitro#4411: Updates the related route-rules type migration and augmentation for prerender and isr.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR only updates docs/JSDoc and does not implement the browser Cache-Control revalidation fix requested in #4041.	Add the browser-facing Cache-Control header or equivalent revalidation behavior for ISR/SWR responses, and keep the documentation in sync.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses a conventional commits docs prefix and matches the documentation-focused changes.
Description check	✅ Passed	The description is directly about the prerender/isr route rule clarification and matches the changed files.
Out of Scope Changes check	✅ Passed	The changes stay focused on prerender/isr documentation and JSDoc, with no unrelated code paths introduced.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 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: 1

🤖 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 `@docs/1.docs/5.routing.md`:
- Around line 669-675: Update the ISR note near the Vercel configuration
guidance to include or link to the browser-cache Cache-Control workaround
documented in `#4041`. Keep the existing explanation that ISR and build-time
prerender should not be combined on the same route.

🪄 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

Run ID: 3c5e786b-42c0-448d-9609-7b70a0add7f3

📥 Commits

Reviewing files that changed from the base of the PR and between c1ff6ba and e0be3a1.

📒 Files selected for processing (2)

• docs/1.docs/5.routing.md
• src/types/route-rules.ts

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
rg -n -C3 'Cache-Control|browser cache|heuristic|stale HTML|revalidation' docs/1.docs/5.routing.md

Repository: nitrojs/nitro

Length of output: 151

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n## Target section\n'
sed -n '650,700p' docs/1.docs/5.routing.md

printf '\n## Search for issue 4041 and cache guidance\n'
rg -n -C2 '`#4041`|4041|Cache-Control|browser cache|stale HTML|revalidation|ISR|prerender' docs . -g '!**/node_modules/**' -g '!**/dist/**' -g '!**/build/**'

Repository: nitrojs/nitro

Length of output: 50371

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n## Target section\n'
sed -n '660,690p' docs/1.docs/5.routing.md

printf '\n## Issue and cache guidance search\n'
rg -n -C3 '`#4041`|4041|Cache-Control|browser cache|stale HTML|revalidation|surrogate-control|no-store|max-age' .

Repository: nitrojs/nitro

Length of output: 20152

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Search for any mention of issue 4041 or cache workarounds in repo docs.
rg -n -C3 '4041|Cache-Control|browser cache|stale HTML|revalidation|surrogate-control|no-store|max-age' docs . -g '!**/node_modules/**' -g '!**/dist/**' -g '!**/build/**'

Repository: nitrojs/nitro

Length of output: 24073

---

Add the browser-cache workaround to the ISR note. This section only covers ISR/prerender incompatibility; include the Cache-Control workaround from #4041 here or link to where it’s documented.

🤖 Prompt for 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.

In `@docs/1.docs/5.routing.md` around lines 669 - 675, Update the ISR note near
the Vercel configuration guidance to include or link to the browser-cache
Cache-Control workaround documented in `#4041`. Keep the existing explanation that
ISR and build-time prerender should not be combined on the same route.