docs: fix misleading middleware example path in routing docs (#4354)

[rafaumeu]

Fixes #4354

Changed the route-scoped middleware example to use ./server/utils/api-auth.ts instead of ./server/middleware/api-auth.ts to avoid confusion with global middleware behavior.

Also added a warning note clarifying that files in server/middleware/ run globally regardless of the route pattern.

[vercel]

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

A member of the Team first needs to authorize it.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5263a2ae-1192-4d61-afd8-a6f8a360f93a

📥 Commits

Reviewing files that changed from the base of the PR and between 1f020b0 and b099fd0.

📒 Files selected for processing (1)

• docs/1.docs/5.routing.md

 ____________________________________
< Come with me if you want to debug. >
 ------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

📝 Walkthrough

Walkthrough

The routing documentation example for route-scoped middleware has the handler path corrected from ./server/middleware/api-auth.ts to ./server/utils/api-auth.ts, and a warning note is added stating that handler files for route-scoped middleware must not reside under server/middleware/ since files there execute globally.

Changes

Routing Docs: Route-Scoped Middleware Fix

Layer / File(s)	Summary
Route-scoped middleware handler path and warning docs/1.docs/5.routing.md	Handler path in the handlers config example changed from ./server/middleware/api-auth.ts to ./server/utils/api-auth.ts; warning note added that files placed under server/middleware/ run globally regardless of the route pattern.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: fix misleading middleware example path in routing docs (#4354)' follows conventional commits format with 'docs' prefix and clearly describes the documentation fix.
Description check	✅ Passed	The description clearly relates to the changeset by explaining the fix to the misleading middleware example path and the added warning note.
Linked Issues check	✅ Passed	The PR addresses both objectives from issue #4354: changing the middleware path from server/middleware/ to server/utils/ and adding clarification about global vs route-scoped middleware.
Out of Scope Changes check	✅ Passed	All changes are within scope—only the routing documentation file was modified to fix the misleading example path and add a warning note as required by issue #4354.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/1.docs/5.routing.md (1)

407-419: ⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Update the duplicate route-scoped middleware example to use the corrected path.

There is a second example of route-scoped middleware at lines 407–419 that still references the old handler path ./server/middleware/api-auth.ts at line 414. This creates documentation inconsistency: the primary example (lines 267–279) has been corrected to ./server/utils/api-auth.ts, but this secondary example contradicts that guidance. Readers may encounter either example and receive conflicting advice.

🔧 Proposed fix to align the second example

     {
       route: "/api/**",
-      handler: "./server/middleware/api-auth.ts",
+      handler: "./server/utils/api-auth.ts",
       middleware: true,
     },

🤖 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 407 - 419, Update the handler path in
the route-scoped middleware example shown at lines 407-419 in the
nitro.config.ts code block. Change the handler path reference from the old
location `./server/middleware/api-auth.ts` to the corrected path
`./server/utils/api-auth.ts` to align with the primary example that was
previously corrected at lines 267-279 and eliminate the documentation
inconsistency.

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

Outside diff comments:
In `@docs/1.docs/5.routing.md`:
- Around line 407-419: Update the handler path in the route-scoped middleware
example shown at lines 407-419 in the nitro.config.ts code block. Change the
handler path reference from the old location `./server/middleware/api-auth.ts`
to the corrected path `./server/utils/api-auth.ts` to align with the primary
example that was previously corrected at lines 267-279 and eliminate the
documentation inconsistency.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 16ce2158-64e2-4780-b667-afc5ba59fbc3

📥 Commits

Reviewing files that changed from the base of the PR and between 7765bcb and 1f020b0.

📒 Files selected for processing (1)

• docs/1.docs/5.routing.md

[pi0]

Thanks for PR but example is correctly using relavant middleware dir since serverDir that enables scanning, is opt-in.