docs(middleware): add middleware composition section

[Sarthak-Shreshtha01]

Add a section demonstrating middleware composition patterns including:

• Combining logger, cors, and auth middleware on a single route
• Execution order and early exit flow in composed chains
• Real-world error handling middleware wrapping downstream execution
• References to factory.createHandlers and hono/combine

Resolves honojs/hono#5355

[Copilot]

🟡 Changes recommended

Unresolved CORS, error exposure, and TypeScript correctness issues remain.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds middleware composition guidance to the Hono documentation.

Changes:

• Demonstrates middleware chaining and execution order.
• Covers early exits and error handling.
• References reusable composition utilities.

File summaries

File	Summary
docs/guides/middleware.md	Adds middleware composition documentation and examples.

Review details

Suppressed comments (4)

docs/guides/middleware.md:391

• This fragment does not match the heading in docs/helpers/factory.md: the repository's heading anchors strip punctuation (createMiddleware() links as #createmiddleware), so factory.createHandlers() resolves as #factorycreatehandlers, not #factory-createhandlers.

- **[`factory.createHandlers()`](/docs/helpers/factory#factory-createhandlers)**: Define a reusable array of middlewares and a handler with complete type safety.

docs/guides/middleware.md:314

• cors() does not always continue to bearerAuth: for an OPTIONS request it returns a 204 response before calling next(). Since this diagram explicitly mentions preflight handling but then shows auth executing, it misstates the chain for browser preflights; show the OPTIONS early-exit branch or qualify the diagram to non-OPTIONS requests.

[cors]         ── (before next: checks origin and preflight headers)
  │
  ▼
[bearerAuth]   ── (before next: validates bearer token)

docs/guides/middleware.md:325

• The CORS middleware sets Access-Control-Allow-* headers before await next(); after next() it only appends Vary: Origin when configured with a non-wildcard origin. Calling this stage 'appends CORS headers' gives the wrong mental model for the response mutation, including on early auth exits.

[cors]         ── (after next: appends CORS headers to response)

docs/guides/middleware.md:316

• bearerAuth does not return a 401 Response directly on invalid credentials; it throws an HTTPException, which Hono's error handler converts to the response and records in c.error. Describe the throw/error-handler path so this section matches the actual early-exit behavior.

  ├─► [Invalid Token] ── early exit: returns 401 Response directly

• Files reviewed: 1/1 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.