Unverified Commit b0843fea authored by Stephanie Dietz's avatar Stephanie Dietz Committed by GitHub

Update middleware docs to include common use cases (#63534)

parent cf9e647f
...@@ -9,10 +9,30 @@ Middleware allows you to run code before a request is completed. Then, based on ...@@ -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. 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 ## 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. 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 ## Example
```ts filename="middleware.ts" switcher ```ts filename="middleware.ts" switcher
...@@ -46,7 +66,7 @@ export const config = { ...@@ -46,7 +66,7 @@ export const config = {
## Matching Paths ## 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` 1. `headers` from `next.config.js`
2. `redirects` from `next.config.js` 2. `redirects` from `next.config.js`
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment