Accept generic type parameters for `NextResponse`

[karlhorky]

Describe the feature you'd like to request

Hi, first of all thanks for your amazing effort on Next.js, great framework 🙌

With the new App Routes coming courtesy of @wyattjoh, @ijjk and @timneutkens with the merge + publish to canary of #45716, the following pattern is now possible in an App Route for eg. an API handler:

import { NextRequest, NextResponse } from 'next/server';

type RequestBody = { zzz: number };
type ResponseBody = { abc: number };

export async function POST(request: NextRequest) {
  const body: RequestBody = await request.json();
  return NextResponse.json({
    abc: 123, // ❌ POST function return type cannot check type of response body object
  });
}

These are using the NextRequest and NextResponse types created by @javivelasco and others.

But the ResponseBody type are not able to be checked easily here.

Ideally, NextResponse would accept generic type parameters (just like the NextApiResponse type currently does for API routes in the pages/api/ directory).

Describe the solution you'd like

It would be amazing to be able to pass generic type parameters into the NextResponse type, enabling a pattern like this:

import { NextRequest, NextResponse } from 'next/server';

type RequestBody = { zzz: number };
type ResponseBody = { abc: number };

export async function POST(request: NextRequest<RequestBody>): NextResponse<ResponseBody> {
  const body: RequestBody = await request.json();
  return NextResponse.json({
    abc: 123, // ✅ POST function return type checks type of response body object
  });
}

Prior Art

• NextApiResponse for API routes in pages/api/ directory: Improve NextApiResponse typing #7841 by @VincentCordobes (reviewed by @Timer and @huv1k)
• @types/express: Request and Response types - which both accept a generic type parameter for the body

Caveats

Edit: Removed this section, because this issue was originally about allowing generic type parameters with NextRequest as well, but this has since changed to only encompass NextResponse

1. Arguably, the NextRequest body is unknown until runtime, so this is better handled instead with Zod or some other runtime validation. But for quick/simple projects without this validation, it's nice to be able to type the request body type.

Describe alternatives you've considered

An alternative would be for TypeScript to make the Response and Request interfaces accept generic type parameters:

• [libdom] Allow Response / Request to be generics microsoft/TypeScript#52777

However, this may be unlikely to happen - a similar suggestion for FormData has been not implemented since 2021:

• FormData methods should take a Generic microsoft/TypeScript#43797

[timneutkens]

Checking the body should live outside of the type Next.js gives you because typing the incoming body gives a false sense of type safety. E.g. I can fetch('yourapi', { body: JSON.stringify({a: 'a', b: 'b'}) }) and your API would not handle it correctly because the body was not validated / sanitized. The recommendation for this would be to use libraries like zod that allow you to define a shape that is validated and then use the inferred type.
I think body needs to be unknown instead of any though.

For the response body you have a point, however I'm not sure if it should be exactly that way, because NextResponse is an extension of Response and Response doesn't take a generic, which when that changes would become a problem.

I had a quick look into it and the change would be something like this:

export declare class NextResponse<B = void> extends Response {
    [INTERNALS]: {
        cookies: ResponseCookies;
        url?: NextURL;
        // Parameter needs to be used in the class in order for it to run type checking
        B: B
    };
    constructor(body?: BodyInit | null, init?: ResponseInit);
    get cookies(): ResponseCookies;
    // json takes in generic.
    static json<T>(body: T, init?: ResponseInit): NextResponse<T>;
    static redirect(url: string | NextURL | URL, init?: number | ResponseInit): NextResponse;
    static rewrite(destination: string | NextURL | URL, init?: MiddlewareResponseInit): NextResponse;
    static next(init?: MiddlewareResponseInit): NextResponse;
}

Will discuss with the rest of the team.

[karlhorky]

Checking the body should live outside of the type Next.js gives you because typing the incoming body gives a false sense of type safety. E.g. I can fetch('yourapi', { body: JSON.stringify({a: 'a', b: 'b'}) }) and your API would not handle it correctly because the body was not validated / sanitized. The recommendation for this would be to use libraries like zod that allow you to define a shape that is validated and then use the inferred type.

Makes sense. Real runtime validation (eg. using Zod) is indeed better. We're teaching this now in the bootcamp 👍 I've changed the title and description

For the response body you have a point, however I'm not sure if it should be exactly that way, because NextResponse is an extension of Response and Response doesn't take a generic, which when that changes would become a problem.

Yeah, I'm not holding my breath that TypeScript will implement generic parameters for Response, even though I'm the one that submitted the issue. If they end up doing it in some crazy future, I guess having a breaking types change to NextResponse would be reasonable...

Will discuss with the rest of the team.

Cool, would be great to get NextResponse generic parameters just at parity with the existing NextApiResponse<...> type that is available in API Routes in the pages/ directory - would be one less thing to hold back transitioning to app/ directory.

---

Alternative

If this could be implemented as a "recipe" or "example" in userland - with not too much code, and still being able to import + use NextResponse from next/server - this may also be acceptable... not as nice as having it built-in for everyone to use out of the box, but it may also work.

Alternative 2

Patching next using patch-package to add the type is always an option, but we're really trying to avoid maintaining custom patches for Next.js, which gets especially complex with the projects the students create.

[karlhorky]

I had a quick look into it and the change would be something like this:

<code block>

Seems like this approach is working mostly for our app code too - copied your update into node_modules/next/dist/server/web/spec-extension/response.d.ts.

For example, both of the responses are checked properly here, when using the return type on the GET Route Handler:

type ResponseBody = { errors: { message: string }[] } | { username: string };

export async function GET(
  request: NextRequest,
): Promise<NextResponse<ResponseBody>> {
  const token = request.cookies.get('sessionToken');
  const user = !token?.value
    ? undefined
    : await getUserByValidSessionToken(token.value);

  if (!user) {
    return NextResponse.json({
      errors: [{ message: 'User not found by session token' }],
    });
  }

  return NextResponse.json({
    username: user.username,
  });
}

Kapture.2023-03-05.at.16.08.12.mp4

Caveat

No excess property checks: One thing you'll notice at the very end of the video above is that the extra a property added in the response does not result in an error.

[karlhorky]

@timneutkens I opened a PR here to continue the discussion:

• Add optional generic parameter to NextResponse #47526

I also included these changes to the code in your comment above:

• I gave the generic parameters better names (not single characters)
• I changed the default value of the generic body parameter from void to unknown, so that the generic argument does not need to be specified

[karlhorky]

Workaround

In the meantime, until the PR above gets reviewed, there is a 2nd workaround without patching next of adding a new declaration file for Next.js. It's a bit messy and it will need to be maintained with any updates that are made to the next package, but it works.

It can be done by adding a next.d.ts file and then updating the "includes" array in your tsconfig.json file to include this file:

next.d.ts

import { NextResponse } from 'next/server';

declare const INTERNALS: unique symbol;

declare module 'next/server' {
  /**
   * Workaround to enable generic type arguments for NextResponse until
   * PR is merged:
   * https://github.com/vercel/next.js/pull/47526
   * Original issue: https://github.com/vercel/next.js/issues/45943
   *
   * Eg.
   *
   * ```ts
   * type ResponseBodyGet = { a: number };
   * export function GET(): NextResponse<ResponseBodyGet> {
   *   if (Math.random() > 0.5) {
   *     return NextResponse.json({ invalid: 'x' }) // ❌ Type 'NextResponse<{ invalid: string; }>' is not assignable to type 'NextResponse<ResponseBodyGet>'.
   *   }
   *   return NextResponse.json({ a: 1 }); // ✅ No error
   * }
   * ```
   */
  export class NextResponse<Body = unknown> extends Response {
    [INTERNALS]: {
      cookies: ResponseCookies;
      url?: NextURL;
      Body?: Body;
    };
    static json<JsonBody>(
      body: JsonBody,
      init?: ResponseInit,
    ): NextResponse<JsonBody>;
  }
}

tsconfig.json

{
  "include": [
    "next-env.d.ts",
+   "next.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts"
  ]
}

Because of declaration merging, this will use the updated type declarations for:

1. NextResponse to allow generic type arguments
2. NextResponse.json() to check against the generic type argument passed

But will still use the types from next/server for anything else eg. NextResponse.redirect()