Add TS types for NextMiddleware (vercel#30578)

This allows TypeScript users to have type safety for middleware functions.

- Closes vercel#30490 

Co-authored-by: Lee Robinson <[email protected]>
Co-authored-by: JJ Kasper <[email protected]>

Author: 3 people

docs/api-reference/next/server.md

@@ -4,19 +4,29 @@ description: Use Middleware to run code before a request is completed.
 
 # next/server
 
-Middleware is created by using a `middleware` function that lives inside a `_middleware` file. The Middleware API is based upon the native [`FetchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent), [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response), and [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) objects.
+The `next/server` module provides several exports for server-only helpers, such as [Middleware](/docs/middleware.md).
+
+## NextMiddleware
+
+Middleware is created by using a `middleware` function that lives inside a `_middleware` file. The Middleware API is based upon the native [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request), [`FetchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent), and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects.
 
 These native Web API objects are extended to give you more control over how you manipulate and configure a response, based on the incoming requests.
 
-The function signature:
+The function signature is defined as follows:
 
 ```ts
-import type { NextRequest, NextFetchEvent } from 'next/server'
+type NextMiddlewareResult = NextResponse | Response | null | undefined
 
-export type Middleware = (
+type NextMiddleware = (
   request: NextRequest,
   event: NextFetchEvent
-) => Promise<Response | undefined> | Response | undefined
+) => NextMiddlewareResult | Promise<NextMiddlewareResult>
+```
+
+It can be imported from `next/server` with the following:
+
+```ts
+import type { NextMiddleware } from 'next/server'
 ```
 
 The function can be a default export and as such, does **not** have to be named `middleware`. Though this is a convention. Also note that you only need to make the function `async` if you are running asynchronous code.

packages/next/server.d.ts

@@ -1,3 +1,4 @@
 export { NextFetchEvent } from 'next/dist/server/web/spec-extension/fetch-event'
 export { NextRequest } from 'next/dist/server/web/spec-extension/request'
 export { NextResponse } from 'next/dist/server/web/spec-extension/response'
+export { NextMiddleware } from 'next/dist/server/web/types'

packages/next/server/web/adapter.ts

@@ -1,4 +1,4 @@
-import type { RequestData, FetchEventResult } from './types'
+import type { NextMiddleware, RequestData, FetchEventResult } from './types'
 import { DeprecationError } from './error'
 import { fromNodeHeaders } from './utils'
 import { NextFetchEvent } from './spec-extension/fetch-event'
@@ -7,7 +7,7 @@ import { NextResponse } from './spec-extension/response'
 import { waitUntilSymbol } from './spec-compliant/fetch-event'
 
 export async function adapter(params: {
-  handler: (request: NextRequest, event: NextFetchEvent) => Promise<Response>
+  handler: NextMiddleware
   page: string
   request: RequestData
 }): Promise<FetchEventResult> {

packages/next/server/web/spec-extension/response.ts

@@ -73,7 +73,7 @@ export class NextResponse extends Response {
     })
   }
 
-  static redirect(url: string | NextURL, status = 302) {
+  static redirect(url: string | NextURL | URL, status = 302) {
     if (!REDIRECTS.has(status)) {
       throw new RangeError(
         'Failed to execute "redirect" on "response": Invalid status code'

packages/next/server/web/types.ts

@@ -1,4 +1,7 @@
 import type { I18NConfig } from '../config-shared'
+import type { NextRequest } from '../web/spec-extension/request'
+import type { NextFetchEvent } from '../web/spec-extension/fetch-event'
+import type { NextResponse } from './spec-extension/response'
 
 export interface NodeHeaders {
   [header: string]: string | string[] | undefined
@@ -31,3 +34,10 @@ export interface FetchEventResult {
   response: Response
   waitUntil: Promise<any>
 }
+
+export type NextMiddlewareResult = NextResponse | Response | null | undefined
+
+export type NextMiddleware = (
+  request: NextRequest,
+  event: NextFetchEvent
+) => NextMiddlewareResult | Promise<NextMiddlewareResult>

test/integration/middleware-typescript/next.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  i18n: {
+    locales: ['en', 'fr', 'nl'],
+    defaultLocale: 'en',
+  },
+}

test/integration/middleware-typescript/pages/interface/[id]/index.tsx

@@ -0,0 +1,3 @@
+export default function Index() {
+  return <p className="title">Dynamic route</p>
+}

test/integration/middleware-typescript/pages/interface/_middleware.ts

@@ -0,0 +1,14 @@
+import { NextMiddleware } from 'next/server'
+
+export const middleware: NextMiddleware = function (request) {
+  return new Response(null, {
+    headers: {
+      'req-url-basepath': request.nextUrl.basePath,
+      'req-url-pathname': request.nextUrl.pathname,
+      'req-url-params': JSON.stringify(request.page.params),
+      'req-url-page': request.page.name || '',
+      'req-url-query': request.nextUrl.searchParams.get('foo') || '',
+      'req-url-locale': request.nextUrl.locale,
+    },
+  })
+}

test/integration/middleware-typescript/pages/interface/static.tsx

@@ -0,0 +1,3 @@
+export default function Index() {
+  return <p className="title">Static route</p>
+}

test/integration/middleware-typescript/pages/redirects/_middleware.ts

@@ -0,0 +1,16 @@
+import { NextMiddleware, NextResponse } from 'next/server'
+
+export const middleware: NextMiddleware = async function (request) {
+  const url = request.nextUrl
+
+  if (url.searchParams.get('foo') === 'bar') {
+    url.pathname = '/redirects/new-home'
+    url.searchParams.delete('foo')
+    return Response.redirect(url)
+  }
+
+  if (url.pathname === '/redirects/old-home') {
+    url.pathname = '/redirects/new-home'
+    return NextResponse.redirect(url)
+  }
+}