From 6840a506e423d016c88b1ba13e94b61b54a90f0f Mon Sep 17 00:00:00 2001 From: BTF Kabir Date: Fri, 17 Jul 2026 11:06:53 -0700 Subject: [PATCH] docs: clarify route-scoped middleware example path Use a non-middleware handler path in the handlers examples and note that middleware auto-scan only applies when serverDir is set. Fixes #4354 --- docs/1.docs/5.routing.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/1.docs/5.routing.md b/docs/1.docs/5.routing.md index 2cf6ec1081..274b755f23 100644 --- a/docs/1.docs/5.routing.md +++ b/docs/1.docs/5.routing.md @@ -271,7 +271,7 @@ export default defineConfig({ handlers: [ { route: "/api/**", - handler: "./server/middleware/api-auth.ts", + handler: "./server/utils/api-auth.ts", middleware: true, }, ], @@ -298,7 +298,7 @@ Nitro route middleware can hook into the request lifecycle. A middleware can modify the request before it is processed, not after. :: -Middleware are auto-registered within the `middleware/` directory. +When [`serverDir`](/config#serverdir) is set, middleware are auto-registered from the `middleware/` directory. ```md middleware/ @@ -323,7 +323,7 @@ export default defineHandler((event) => { }); ``` -Middleware in `middleware/` directory are automatically registered for all routes. If you want to register a middleware for a specific route, see [Object Syntax Event Handler](https://h3.dev/guide/basics/handler#object-syntax). +With [`serverDir`](/config#serverdir) enabled, files in the `middleware/` directory are automatically registered for all routes. If you want to register a middleware for a specific route, see [Object Syntax Event Handler](https://h3.dev/guide/basics/handler#object-syntax) or [route-scoped middleware](#route-scoped-middleware). ::note Returning anything from a middleware will close the request and should be avoided! Any returned value from middleware will be the response and further code will not be executed however **this is not recommended to do!** @@ -408,14 +408,16 @@ export default defineConfig({ handlers: [ { route: "/api/**", - handler: "./server/middleware/api-auth.ts", + handler: "./server/utils/api-auth.ts", middleware: true, }, ], }); ``` -Unlike global middleware (registered in the `middleware/` directory which match `/**`), route-scoped middleware only run for requests matching the specified pattern. +Unlike global middleware (auto-registered from the `middleware/` directory when [`serverDir`](/config#serverdir) is set, matching `/**`), route-scoped middleware only run for requests matching the specified pattern. + +Prefer placing route-scoped handler files outside `middleware/` (as in the example above) so directory scanning does not also register them globally when `serverDir` is enabled. ## Error handling