From b0843fea2662c38beb16c6b2d50d23b44e79ea1f Mon Sep 17 00:00:00 2001
From: Stephanie Dietz <49788645+StephDietz@users.noreply.github.com>
Date: Mon, 25 Mar 2024 14:56:48 -0500
Subject: [PATCH] Update middleware docs to include common use cases  (#63534)

---
 .../01-routing/13-middleware.mdx              | 22 ++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/docs/02-app/01-building-your-application/01-routing/13-middleware.mdx b/docs/02-app/01-building-your-application/01-routing/13-middleware.mdx
index 99e96747946c0..3f5979c48cfa8 100644
--- a/docs/02-app/01-building-your-application/01-routing/13-middleware.mdx
+++ b/docs/02-app/01-building-your-application/01-routing/13-middleware.mdx
@@ -9,10 +9,30 @@ Middleware allows you to run code before a request is completed. Then, based on
 
 Middleware runs before cached content and routes are matched. See [Matching Paths](#matching-paths) for more details.
 
+## Use Cases
+
+Integrating Middleware into your application can lead to significant improvements in performance, security, and user experience. Some common scenarios where Middleware is particularly effective include:
+
+- Authentication and Authorization: Ensure user identity and check session cookies before granting access to specific pages or API routes.
+- Server-Side Redirects: Redirect users at the server level based on certain conditions (e.g., locale, user role).
+- Path Rewriting: Support A/B testing, feature rollouts, or legacy paths by dynamically rewriting paths to API routes or pages based on request properties.
+- Bot Detection: Protect your resources by detecting and blocking bot traffic.
+- Logging and Analytics: Capture and analyze request data for insights before processing by the page or API.
+- Feature Flagging: Enable or disable features dynamically for seamless feature rollouts or testing.
+
+Recognizing situations where middleware may not be the optimal approach is just as crucial. Here are some scenarios to be mindful of:
+
+- Complex Data Fetching and Manipulation: Middleware is not designed for direct data fetching or manipulation, this should be done within Route Handlers or server-side utilities instead.
+- Heavy Computational Tasks: Middleware should be lightweight and respond quickly or it can cause delays in page load. Heavy computational tasks or long-running processes should be done within dedicated Route Handlers.
+- Extensive Session Management: While Middleware can manage basic session tasks, extensive session management should be managed by dedicated authentication services or within Route Handlers.
+- Direct Database Operations: Performing direct database operations within Middleware is not recommended. Database interactions should done within Route Handlers or server-side utilities.
+
 ## Convention
 
 Use the file `middleware.ts` (or `.js`) in the root of your project to define Middleware. For example, at the same level as `pages` or `app`, or inside `src` if applicable.
 
+> **Note**: While only one `middleware.ts` file is supported per project, you can still organize your middleware logic modularly. Break out middleware functionalities into separate `.ts` or `.js` files and import them into your main `middleware.ts` file. This allows for cleaner management of route-specific middleware, aggregated in the `middleware.ts` for centralized control. By enforcing a single middleware file, it simplifies configuration, prevents potential conflicts, and optimizes performance by avoiding multiple middleware layers.
+
 ## Example
 
 ```ts filename="middleware.ts" switcher
@@ -46,7 +66,7 @@ export const config = {
 
 ## Matching Paths
 
-Middleware will be invoked for **every route in your project**. The following is the execution order:
+Middleware will be invoked for **every route in your project**. Given this, it's crucial to use matchers to precisely target or exclude specific routes. The following is the execution order:
 
 1. `headers` from `next.config.js`
 2. `redirects` from `next.config.js`