Add new middleware docs #37514

molebox · 2022-06-07T14:23:23Z

This PR adds new content for the middleware docs. Including the new APIs, how to use them, common questions around middleware, and code examples.

Bug

Related issues linked using fixes #number
Integration tests added
Errors have helpful link attached, see contributing.md

Feature

Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
Related issues linked using fixes #number
Integration tests added
Documentation added
Telemetry added. In case of a feature if it's used or not.
Errors have helpful link attached, see contributing.md

Documentation / Examples

Make sure the linting passes by running pnpm lint
The examples guidelines are followed from our contributing doc

docs/advanced-features/middleware.md

@cramforce

…37556) This commit enables the following patterns in Middleware: ```ts // with a dot notation const { ENV_VAR, "ENV-VAR": myEnvVar } = process.env; // or with an object access const { ENV_VAR2, "ENV-VAR2": myEnvVar2 } = process["env"]; ``` ### Related - @cramforce asked this fixed here: #37514 (comment) ## Feature - [x] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. - [x] Related issues linked using `fixes #number` - [x] Integration tests added - [ ] Documentation added - [ ] Telemetry added. In case of a feature if it's used or not. - [ ] Errors have helpful link attached, see `contributing.md`

docs/advanced-features/middleware.md

timeyoutakeit

This looks really good!!

docs/advanced-features/middleware.md

docs/api-routes/edge-api-routes.md

docs/advanced-features/middleware.md

Co-authored-by: Amy Burns <amy.burns@vercel.com>

leerob · 2022-06-24T14:55:52Z

docs/advanced-features/middleware.md

+
+| --------- | ------------------------------------------------------------------------------------------ |
+
+| `v12.2.0` | Middleware GA |


leerob · 2022-06-24T14:58:01Z

docs/advanced-features/middleware.md

-Middleware enables you to run code before a request is completed. Based on the user's incoming request, you can modify the response by rewriting, redirecting, adding headers, or even streaming HTML.
+Middleware allows you to run code before a request is completed, then based on the incoming request, you can modify the response by rewriting, redirecting, adding headers, or setting cookies.
+
+When a request is made, it will first hit the Middleware, _then_ the cache, meaning you can personalize static content and implement authentication, run A/B tests, deliver personalized pages based on geolocation, and perform bot protection.


Suggested change

When a request is made, it will first hit the Middleware, _then_ the cache, meaning you can personalize static content and implement authentication, run A/B tests, deliver personalized pages based on geolocation, and perform bot protection.

Middleware runs _before_ cached content, so you can personalize static files and pages. Common examples of Middleware would be authentication, A/B testing, localized pages, bot protection, and more.

leerob · 2022-06-24T14:58:20Z

docs/advanced-features/middleware.md

+
+When a request is made, it will first hit the Middleware, _then_ the cache, meaning you can personalize static content and implement authentication, run A/B tests, deliver personalized pages based on geolocation, and perform bot protection.
+
+## Summary of Middleware


Suggested change

## Summary of Middleware

## Quickstart

Or similar

leerob · 2022-06-24T14:58:47Z

docs/advanced-features/middleware.md

+
+## Summary of Middleware
+
+- You create a single `middleware.ts` or `middleware.js` file at your projects root, with an exported function


Suggested change

- You create a single `middleware.ts` or `middleware.js` file at your projects root, with an exported function

- Create a `middleware.ts` (or `middleware.js`) file at the root of your project

leerob · 2022-06-24T15:00:13Z

docs/advanced-features/middleware.md

+## Summary of Middleware
+
+- You create a single `middleware.ts` or `middleware.js` file at your projects root, with an exported function
+- The function can be a named, or default export. If the function is a named export, then is **must** be called `middleware`. For a default export, you are free to name it anything you like


Suggested change

- The function can be a named, or default export. If the function is a named export, then is **must** be called `middleware`. For a default export, you are free to name it anything you like

- Export a function named `middleware`

This feels like a strange this to emphasize so early. Let's put them on the happy path and then add a caveat somewhere at the bottom of the page for default exports.

leerob · 2022-06-24T15:59:03Z

docs/api-routes/edge-api-routes.md

+
+API Routes can be configured to run at the Edge using an experimental flag. When deployed on Vercel, these API Routes run as [Edge Functions](https://vercel.com/docs/concepts/functions/vercel-edge-functions).
+
+Edge API Routes are similar to API Routes but with different infrastructure:


Suggested change

Edge API Routes are similar to API Routes but with different infrastructure:

Edge API Routes are similar to API Routes but use the Edge Runtime:

leerob · 2022-06-24T15:59:27Z

docs/api-routes/edge-api-routes.md

+- On every invocation API Routes are run from the same region
+- Edge API Routes are copied across the [Vercel Edge Network](https://vercel.com/docs/concepts/edge-network/overview), so on every invocation, the region that is closets to you will run the function, reducing latency massively


Suggested change

- On every invocation API Routes are run from the same region

- Edge API Routes are copied across the [Vercel Edge Network](https://vercel.com/docs/concepts/edge-network/overview), so on every invocation, the region that is closets to you will run the function, reducing latency massively

This isn't relevant to open-source Next.js - Vercel specific stuff 👍

leerob · 2022-06-24T16:00:13Z

docs/api-routes/edge-api-routes.md

+Unlike API Routes, Edge API Routes:
+
+- Can stream responses
+- Run _after_ the cache
+- Can cache responses
+- Have zero cold starts


Suggested change

Unlike API Routes, Edge API Routes:

- Can stream responses

- Run _after_ the cache

- Can cache responses

- Have zero cold starts

Unlike API Routes, Edge API Routes:

- Can stream responses

- Run _after_ the cache

You can cache API routes. and cold boots relates to the infra provider, so let's put that in Vercel docs.

It's more about the edge runtime.

leerob · 2022-06-24T16:01:05Z

docs/api-routes/edge-api-routes.md

+### API Route
+
+```typescript
+import type { NextApiRequest, NextApiResponse } from 'next'
+
+export default (req: NextApiRequest, res: NextApiResponse) => {
+  res
+    .status(200)
+    .json({ name: `Hello, from ${req.url} I'm a Serverless Function'` })
+}
+```
+
+### Edge API Route


Suggested change

### API Route

```typescript

import type { NextApiRequest, NextApiResponse } from 'next'

export default (req: NextApiRequest, res: NextApiResponse) => {

res

.status(200)

.json({ name: `Hello, from ${req.url} I'm a Serverless Function'` })

}

```

### Edge API Route

Let's just show Edge API routes directly, we have other docs on normal API routes

leerob · 2022-06-24T16:01:28Z

docs/api-routes/edge-api-routes.md

+  - Libraries using Node.js APIs can't be used in Edge API Routes
+  - Dynamic code execution (such as `eval`) is not allowed
+
+For more information on limitations when using Edge API Routes, see the Vercel Edge Functions [Limitations documentation](https://vercel.com/docs/concepts/functions/vercel-edge-functions/limitations).


This should be the limitations of the Edge Runtime, nothing to do with Vercel 👍

jescalan

This is great!

jescalan · 2022-06-23T21:07:53Z

docs/advanced-features/middleware.md

+- You create a single `middleware.ts` or `middleware.js` file at your projects root, with an exported function
+- The function can be a named, or default export. If the function is a named export, then is **must** be called `middleware`. For a default export, you are free to name it anything you like
+  ```js
+  //named export


Suggested change

//named export

// named export

jescalan · 2022-06-24T16:11:48Z

docs/api-routes/edge-api-routes.md

+- Can stream responses
+- Run _after_ the cache
+- Can cache responses
+- Have zero cold starts


Might be worth linking to some context on what a cold start is here

leerob · 2022-06-26T15:53:41Z

Replaced by #37992.

Initial outline added for middleware docs

f903c34

ijjk added area: documentation labels Jun 7, 2022

cramforce requested changes Jun 7, 2022

View reviewed changes

cramforce reviewed Jun 7, 2022

View reviewed changes

docs/advanced-features/middleware.md Outdated Show resolved Hide resolved

Schniz mentioned this pull request Jun 8, 2022

[middleware] support destructuring for env vars in static analysis #37556

Merged

6 tasks

Feedback changes - not included new user agent yet

08c812e

feugy mentioned this pull request Jun 13, 2022

feat(middleware)!: forbids middleware response body #36835

Merged

7 tasks

molebox added 12 commits June 20, 2022 12:02

Merge branch 'canary' into middleware-docs

8f10228

edge api routes docs

9476a0b

middleware page some cleanup

879d58c

Merge branch 'canary' into middleware-docs

273dec4

moved api stuff to next server, added useragent

861b526

waitUntil example added

bf087f4

Updated env vars section

47e37b5

Merge branch 'canary' into middleware-docs

cae2e64

Added cookies on the request object example

4e9c1bf

Merge branch 'canary' into middleware-docs

3176b4e

fixed naming

7291023

fixed import typo

82b18b8

timeyoutakeit reviewed Jun 22, 2022

View reviewed changes

docs/advanced-features/middleware.md Outdated Show resolved Hide resolved

timeyoutakeit reviewed Jun 22, 2022

View reviewed changes

molebox added 2 commits June 22, 2022 19:37

Merge branch 'canary' into middleware-docs

b5d0d41

Amy feedback

45e528f

molebox marked this pull request as ready for review June 22, 2022 17:37

molebox requested review from timneutkens, ijjk, shuding and styfle as code owners June 22, 2022 17:37

molebox requested review from huozhi, padmaia, leerob and balazsorban44 as code owners June 22, 2022 17:37

styfle requested a review from javivelasco June 22, 2022 18:22

timeyoutakeit reviewed Jun 23, 2022

View reviewed changes

docs/advanced-features/middleware.md Outdated Show resolved Hide resolved

Update docs/advanced-features/middleware.md

1e97c04

Co-authored-by: Amy Burns <amy.burns@vercel.com>

molebox requested a review from cramforce June 23, 2022 06:36

leerob reviewed Jun 24, 2022

View reviewed changes

jescalan approved these changes Jun 24, 2022

View reviewed changes

This was referenced Jun 24, 2022

Add new middleware docs - updates molebox/next.js#1

Closed

Update Middleware documentation #37992

Closed

leerob closed this Jun 26, 2022

github-actions bot locked as resolved and limited conversation to collaborators Jul 27, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add new middleware docs #37514

Add new middleware docs #37514

molebox commented Jun 7, 2022 •

edited

Loading

timeyoutakeit left a comment

leerob Jun 24, 2022

leerob Jun 24, 2022

leerob Jun 24, 2022

leerob Jun 24, 2022

leerob Jun 24, 2022

leerob Jun 24, 2022

leerob Jun 24, 2022

leerob Jun 24, 2022

leerob Jun 24, 2022

leerob Jun 24, 2022

jescalan left a comment

jescalan Jun 23, 2022

jescalan Jun 24, 2022

leerob commented Jun 26, 2022


		\| --------- \| ------------------------------------------------------------------------------------------ \|

		\| `v12.2.0` \| Middleware GA \|

	\| `v12.2.0` \| Middleware GA \|
	\| `v12.2.0` \| Middleware is stable \|

	When a request is made, it will first hit the Middleware, _then_ the cache, meaning you can personalize static content and implement authentication, run A/B tests, deliver personalized pages based on geolocation, and perform bot protection.
	Middleware runs _before_ cached content, so you can personalize static files and pages. Common examples of Middleware would be authentication, A/B testing, localized pages, bot protection, and more.


		When a request is made, it will first hit the Middleware, _then_ the cache, meaning you can personalize static content and implement authentication, run A/B tests, deliver personalized pages based on geolocation, and perform bot protection.

		## Summary of Middleware


		## Summary of Middleware

		- You create a single `middleware.ts` or `middleware.js` file at your projects root, with an exported function

	- You create a single `middleware.ts` or `middleware.js` file at your projects root, with an exported function
	- Create a `middleware.ts` (or `middleware.js`) file at the root of your project

	- The function can be a named, or default export. If the function is a named export, then is must be called `middleware`. For a default export, you are free to name it anything you like
	- Export a function named `middleware`


		API Routes can be configured to run at the Edge using an experimental flag. When deployed on Vercel, these API Routes run as [Edge Functions](https://vercel.com/docs/concepts/functions/vercel-edge-functions).

		Edge API Routes are similar to API Routes but with different infrastructure:

		- On every invocation API Routes are run from the same region
		- Edge API Routes are copied across the [Vercel Edge Network](https://vercel.com/docs/concepts/edge-network/overview), so on every invocation, the region that is closets to you will run the function, reducing latency massively

Add new middleware docs #37514

Add new middleware docs #37514

Conversation

molebox commented Jun 7, 2022 • edited Loading

Bug

Feature

Documentation / Examples

timeyoutakeit left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jescalan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

leerob commented Jun 26, 2022

molebox commented Jun 7, 2022 •

edited

Loading