docs: Replace Middleware docs to Proxy #84709

devjiwonchoi · 2025-10-09T21:35:38Z

Note

Best reviewed by each commit for better diff view.

This PR clones the Middleware docs for Proxy and removes the Middleware docs.

Did not clone the list of docs:

errors/middleware-upgrade.mdx - It's a middleware upgrade guide from v12.2
errors/beta-middleware.mdx - It's an error when using middleware before v12.2
errors/returning-response-body.mdx - Legacy behavior from versions < v12.2

devjiwonchoi · 2025-10-09T21:35:54Z

This stack of pull requests is managed by Graphite. Learn more about stacking.

github-actions · 2025-10-09T21:36:02Z

Hi there 👋

It looks like this PR introduces broken links to the docs, please take a moment to fix them before merging:

Broken link	Type	File
/docs/app/getting-started/#middleware	link	/docs/01-app/03-api-reference/03-file-conventions/middleware.mdx
/docs/app/guides/self-hosting#proxy	hash	/docs/01-app/03-api-reference/03-file-conventions/proxy.mdx

Thank you 🙏

graphite-app · 2025-10-16T16:40:25Z

docs/01-app/03-api-reference/03-file-conventions/proxy.mdx

+  })
+  cookie = response.cookies.get('vercel')
+  console.log(cookie) // => { name: 'vercel', value: 'fast', Path: '/' }
+  // The outgoing response will have a `Set-Cookie:vercel=fast;path=/test` header.


The comment in the cookie example doesn't match the code implementation. The code sets the cookie path to '/' on line 321, but the comment incorrectly states the outgoing response will have path=/test. The comment should be updated to Set-Cookie:vercel=fast;path=/ to accurately reflect the code behavior.

Suggested change

// The outgoing response will have a `Set-Cookie:vercel=fast;path=/test` header.

// The outgoing response will have a `Set-Cookie:vercel=fast;path=/` header.

Spotted by Graphite Agent

Is this helpful? React 👍 or 👎 to let us know.

errors/proxy-request-page.mdx

icyJoseph · 2025-10-16T20:30:51Z

errors/deleting-query-params-in-proxy.mdx

+
+export default function proxy(request: NextRequest) {
+  const nextUrl = request.nextUrl
+  nextUrl.searchParams.delete('key') // <-- this is now possible! 🎉


Suggested change

nextUrl.searchParams.delete('key') // <-- this is now possible! 🎉

nextUrl.searchParams.delete('key') // <-- this is now possible!

No emojis ~

It's a clean copy from middleware docs 😂 Remove from both?

https://github.com/vercel/next.js/blob/c6cd1f455f5c55530ce894aad3210ef5f6003a77/errors/deleting-query-params-in-middlewares.mdx

🙏 yes haha

icyJoseph · 2025-10-17T09:07:20Z

docs/01-app/03-api-reference/03-file-conventions/proxy.mdx

+
+## Version history
+
+| Version   | Changes                                                                                    |


I guess we can keep the Middleware in the history here, and add a v16 row, with the renaming

If one uses v14, or v13, it'll be middleware

errors/proxy-parse-user-agent.mdx

icyJoseph · 2025-10-17T11:22:55Z

docs/01-app/03-api-reference/03-file-conventions/proxy.mdx

+    - app/api-reference/functions/next-response
+---
+
+The `proxy.js|ts` file is used to write [Proxy](/docs/app/getting-started/route-handlers-and-proxy#proxy) and run code on the server before a request is completed. Then, based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly.


I guess this link is gonna be broken, since proxy is separate from route handlers in: https://github.com/vercel/next.js/pull/84708/files

Oh good catch, will replace

devjiwonchoi · 2025-10-17T11:35:04Z

Noticed the docs link validation was accurate 😅 should we replace the doc below at #84964?

next.js/docs/01-app/02-guides/self-hosting.mdx

Lines 25 to 29 in 8bc8dc3

    
           ## Middleware 
        
           [Middleware](/docs/app/api-reference/file-conventions/middleware) works self-hosted with zero configuration when deploying using `next start`. Since it requires access to the incoming request, it is not supported when using a [static export](/docs/app/guides/static-exports). 
        
           Middleware uses the [Edge runtime](/docs/app/api-reference/edge), a subset of all available Node.js APIs to help ensure low latency, since it may run in front of every route or asset in your application. If you do not want this, you can use the [full Node.js runtime](/blog/next-15-2#nodejs-middleware-experimental) to run Middleware.

EDIT: Added to #84964

Co-authored-by: Joseph <sephxd1234@gmail.com>

- Example of "Set-Cookie:vercel=fast;path=/" - keep the Middleware in the history

Co-authored-by: Joseph <sephxd1234@gmail.com>

ijjk added created-by: Next.js team PRs by the Next.js team. Documentation Related to Next.js' official documentation. labels Oct 9, 2025

This was referenced Oct 9, 2025

docs: Split "Get Started: Route Handlers and Middleware" to Route Handlers and Proxy #84708

Merged

docs: Deprecation of Middleware #84710

Merged

Add Learn more docs to Middleware deprecation warning #84711

Merged

devjiwonchoi changed the title ~~Clean-clone Middleware docs for Proxy~~ docs: Clone Middleware docs for Proxy Oct 9, 2025

devjiwonchoi mentioned this pull request Oct 10, 2025

Deprecate Middleware API and add Proxy API #84764

Merged

devjiwonchoi force-pushed the jiwon/10-09-docs_split_get_started_route_handlers_and_middleware_to_route_handlers_and_proxy_ branch from 75f6ec0 to a3cbfa4 Compare October 16, 2025 16:36

devjiwonchoi force-pushed the jiwon/10-09-docs_clone_middleware_docs_for_proxy branch from ba8255a to 1b7ab72 Compare October 16, 2025 16:36

devjiwonchoi marked this pull request as ready for review October 16, 2025 16:38

graphite-app bot reviewed Oct 16, 2025

View reviewed changes

vercel bot reviewed Oct 16, 2025

View reviewed changes

errors/proxy-request-page.mdx Outdated Show resolved Hide resolved

icyJoseph reviewed Oct 16, 2025

View reviewed changes

devjiwonchoi force-pushed the jiwon/10-09-docs_split_get_started_route_handlers_and_middleware_to_route_handlers_and_proxy_ branch from a3cbfa4 to d12cb23 Compare October 17, 2025 01:13

devjiwonchoi force-pushed the jiwon/10-09-docs_clone_middleware_docs_for_proxy branch from 1b7ab72 to 91f1897 Compare October 17, 2025 01:13

icyJoseph reviewed Oct 17, 2025

View reviewed changes

devjiwonchoi force-pushed the jiwon/10-09-docs_split_get_started_route_handlers_and_middleware_to_route_handlers_and_proxy_ branch from d12cb23 to 0091bdd Compare October 17, 2025 10:41

devjiwonchoi force-pushed the jiwon/10-09-docs_clone_middleware_docs_for_proxy branch from cde5fd5 to e24ff30 Compare October 17, 2025 10:41

vercel bot reviewed Oct 17, 2025

View reviewed changes

errors/proxy-parse-user-agent.mdx Outdated Show resolved Hide resolved

devjiwonchoi added a commit that referenced this pull request Oct 17, 2025

Address comment #84709 (comment)

cea9bc6

icyJoseph reviewed Oct 17, 2025

View reviewed changes

icyJoseph approved these changes Oct 17, 2025

View reviewed changes

devjiwonchoi changed the title ~~docs: Clone Middleware docs for Proxy~~ docs: Replace Middleware docs to Proxy Oct 17, 2025

devjiwonchoi changed the base branch from jiwon/10-09-docs_split_get_started_route_handlers_and_middleware_to_route_handlers_and_proxy_ to graphite-base/84709 October 17, 2025 13:40

devjiwonchoi and others added 3 commits October 17, 2025 16:01

Clean-clone Middleware docs for Proxy

6ccc342

Replace terms Middleware to Proxy

8dedf1c

Address comments suggestion for fixing in both proxy and middleware docs

5f3ba50

Co-authored-by: Joseph <sephxd1234@gmail.com>

devjiwonchoi and others added 3 commits October 17, 2025 16:01

Address comments

a552ec6

- Example of "Set-Cookie:vercel=fast;path=/" - keep the Middleware in the history

Address comment #84709 (comment)

08fa074

Update route-handlers-and-middleware link

8965f0c

Co-authored-by: Joseph <sephxd1234@gmail.com>

devjiwonchoi force-pushed the graphite-base/84709 branch from 0091bdd to fd8b4c5 Compare October 17, 2025 14:04

devjiwonchoi force-pushed the jiwon/10-09-docs_clone_middleware_docs_for_proxy branch from c6b1b85 to 8965f0c Compare October 17, 2025 14:04

devjiwonchoi changed the base branch from graphite-base/84709 to canary October 17, 2025 14:04

devjiwonchoi merged commit 71ce95d into canary Oct 17, 2025
146 of 147 checks passed

devjiwonchoi deleted the jiwon/10-09-docs_clone_middleware_docs_for_proxy branch October 17, 2025 14:13

devjiwonchoi mentioned this pull request Oct 17, 2025

doc: Update guides to use proxy language #84964

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: Replace Middleware docs to Proxy #84709

docs: Replace Middleware docs to Proxy #84709

Uh oh!

devjiwonchoi commented Oct 9, 2025 •

edited

Loading

Uh oh!

devjiwonchoi commented Oct 9, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Oct 9, 2025 •

edited

Loading

Uh oh!

graphite-app bot Oct 16, 2025

Uh oh!

Uh oh!

icyJoseph Oct 16, 2025 •

edited

Loading

Uh oh!

devjiwonchoi Oct 16, 2025

Uh oh!

icyJoseph Oct 16, 2025

Uh oh!

icyJoseph Oct 17, 2025

Uh oh!

Uh oh!

icyJoseph Oct 17, 2025

Uh oh!

devjiwonchoi Oct 17, 2025

Uh oh!

devjiwonchoi commented Oct 17, 2025 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	// The outgoing response will have a `Set-Cookie:vercel=fast;path=/test` header.
	// The outgoing response will have a `Set-Cookie:vercel=fast;path=/` header.

	nextUrl.searchParams.delete('key') // <-- this is now possible! 🎉
	nextUrl.searchParams.delete('key') // <-- this is now possible!

docs: Replace Middleware docs to Proxy #84709

docs: Replace Middleware docs to Proxy #84709

Uh oh!

Conversation

devjiwonchoi commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devjiwonchoi commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

graphite-app bot Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

icyJoseph Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devjiwonchoi Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

icyJoseph Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

icyJoseph Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

icyJoseph Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

devjiwonchoi Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

devjiwonchoi commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

devjiwonchoi commented Oct 9, 2025 •

edited

Loading

devjiwonchoi commented Oct 9, 2025 •

edited

Loading

github-actions bot commented Oct 9, 2025 •

edited

Loading

icyJoseph Oct 16, 2025 •

edited

Loading

devjiwonchoi commented Oct 17, 2025 •

edited

Loading