fix(next): update rest route handler types for Next.js 15.5 compatibility

[rubixvi]

Fixes #13527.

When upgrading to Next.js 15.5 with Payload, you might experience a runtime or build error similar to this:

Type error: Type 'typeof import("/src/app/(payload)/api/graphql/route")' does not satisfy the expected type 'RouteHandlerConfig<"/api/graphql">'.
  Types of property 'OPTIONS' are incompatible.
    Type '(request: Request, args: { params: Promise<{ slug: string[]; }>; }) => Promise<Response>' is not assignable to type '(request: NextRequest, context: { params: Promise<{}>; }) => void | Promise<void> | Response | Promise<Response>'.
      Types of parameters 'args' and 'context' are incompatible.
        Type '{ params: Promise<{}>; }' is not assignable to type '{ params: Promise<{ slug: string[]; }>; }'.
          Types of property 'params' are incompatible.
            Type 'Promise<{}>' is not assignable to type 'Promise<{ slug: string[]; }>'.
              Property 'slug' is missing in type '{}' but required in type '{ slug: string[]; }'.

This is because Next.js route types are now stricter. Our REST handler is nested within a catch-all /api/[...slug] route, so the slug param will exist in the handler—but the same handler is re-used for the /api/graphql OPTIONS route, which is not nested within the slug param and so it will not exist as the types suggest.

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1211115021865680

[rubixvi]

Had to rebase as I had the wrong commit message, being 15.2 rather than 15.5.

[jacobsfletch]

@rubixvi build is still failing here:

Type error: Route "src/app/(payload)/api/[...slug]/route.ts" has an invalid "GET" export:
  Type "{ params: Promise<{ slug?: string[] | undefined; }>; } | undefined" is not a valid type for the function's second argument.
    Expected "RouteContext", got "{ params: Promise<{ slug?: string[] | undefined; }>; } | undefined".
      Expected "RouteContext", got "undefined".

Also I'm not sure this is exactly true:

In Next.js 15.5, static route handlers are typed as (request: Request) => …, while dynamic routes are (request: Request, params: { params: Promise<…> }) => ….
Prior to this change, Payload’s helpers always required the second argument, which caused type errors and forced users to manually provide a dummy params.

It seems like Next.js route types are now stricter. Our REST handler is nested within a catch-all /api/[...slug] route, so the slug param will exist in the handler—but the same handler is re-used for the gql routes for OPTIONS, which are not nested within the slug param and so it will not exist as the types suggest. I think all we need to do here is make the slug param optional.

I'm going to take a stab at resolving this. I'll try and push to your repo.

Update: 0588b61 works, updating the PR description to reflect this.

[rubixvi]

Confirmed on my end, updating the type to slug?: string[] resolves the issue. The additional guard isn’t needed since /api correctly falls through to a 404.

[jacobsfletch]

The additional guard isn’t needed since /api correctly falls through to a 404.

Yea that and if you make an OPTIONS request to /api/graphql, it hits this same REST handler without params, but this is fine because we safely access the slug property here.

[raktimkashyap]

Hello Everyone!
I am still facing the same issue while building the app.
My next js project is in next js v15.5.0. and I have installed payload cms on top of it using

npx create-payload-app@latest (v3.53.0)
running npm run build still gives me this error:

Type error: Type 'typeof import("......../src/app/(payload)/api/graphql/route")' does not satisfy the expected type 'RouteHandlerConfig<"/api/graphql">'.
  Types of property 'OPTIONS' are incompatible.
    Type '(request: Request, args: { params: Promise<{ slug: string[]; }>; }) => Promise<Response>' is not assignable to type '(request: NextRequest, context: { params: Promise<{}>; }) => void | Response | Promise<Response> | Promise<void>'.
      Types of parameters 'args' and 'context' are incompatible.
        Type '{ params: Promise<{}>; }' is not assignable to type '{ params: Promise<{ slug: string[]; }>; }'.
          Types of property 'params' are incompatible.
            Type 'Promise<{}>' is not assignable to type 'Promise<{ slug: string[]; }>'.
              Property 'slug' is missing in type '{}' but required in type '{ slug: string[]; }'.
const handler = {} as typeof import("..\\..\\src\\app\\(payload)\\api\\graphql\\route.js")
handler satisfies RouteHandlerConfig<"/api/graphql">

After reading this thread. I created a project with npx create-payload-app@latest -t website and tried to build it.
It was built without the error.

So I guess the issue is still there when installing payload cms on top of next js.

Any suggestions?
Thank you :)

[jacobsfletch]

@raktimkashyap this patch hasn't been released yet. Our release bot will post a comment here when it goes out. In the meantime you could install one of our nightly canaries, looks like this change went out in v3.54.0-canary.1.

[raktimkashyap]

@jacobsfletch Thanks a lot! I will try out the canary build in the mean time! :)

[github-actions]

🚀 This is included in version v3.54.0