TypeScript Compatibility Issue with Next.js 15.5.0

[btnalexandre]

Hello @omermecitoglu I'm back with a new error 😄

Environment

• Next.js: 15.5.0
• @omer-x/next-openapi-route-handler: 2.0.0
• TypeScript: 5.5.3
• React: 19.1.1
• zod: 3.24.1

Executed command

next build

Error Message

Type error: Type 'typeof import("src/app/api/v1/orders/[id]/route")' does not satisfy the expected type 'RouteHandlerConfig<"/api/v1/orders/[id]">'.
  Types of property 'GET' are incompatible.
    Type 'RouteMethodHandler<ZodObjectDef<{ id: ZodString; }, "strip", ZodTypeAny>, Request, Response>' is not assignable to type '((request: NextRequest, context: { params: Promise<{ id: string; }>; }) => void | Promise<void> | Response | Promise<Response>) | undefined'.
      Type 'RouteMethodHandler<ZodObjectDef<{ id: ZodString; }, "strip", ZodTypeAny>, Request, Response>' is not assignable to type '(request: NextRequest, context: { params: Promise<{ id: string; }>; }) => void | Promise<void> | Response | Promise<Response>'.
        Types of parameters 'context' and 'context' are incompatible.
          Type '{ params: Promise<{ id: string; }>; }' is not assignable to type 'RouteHandlerContext<ZodObjectDef<{ id: ZodString; }, "strip", ZodTypeAny>>'.
            Types of property 'params' are incompatible.
              Type 'Promise<{ id: string; }>' is not assignable to type 'Promise<ZodObjectDef<{ id: ZodString; }, "strip", ZodTypeAny>>'.
                Type '{ id: string; }' is missing the following properties from type 'ZodObjectDef<{ id: ZodString; }, "strip", ZodTypeAny>': typeName, shape, catchall, unknownKeys

Code

Route file :

import defineRoute from "@omer-x/next-openapi-route-handler";
import { NextResponse } from "next/server";
import { z } from "zod";
import { validateApiKey } from "~/lib/api";
import { handleApiErrors } from "~/lib/handleApiErrors";
import { getWCOrder } from "~/lib/woocommerce/orders/orders";
import { OrderDTO } from "~/lib/woocommerce/schemas/orders.schemas";

export const { GET } = defineRoute({
  operationId: "retrieveOrder",
  method: "GET",
  summary: "Retrieve an order",
  description: "Retrieve an order from your store",
  tags: ["Orders"],
  pathParams: z.object({
    id: z.string(),
  }),
  middleware: (handler) => async (req, context) => {
    const { storeId } = await validateApiKey({ req });

    if (!storeId) {
      return NextResponse.json({ message: "Unauthorized" }, { status: 401 });
    }

    req.headers.set("x-store-id", storeId);
    return handler(req, context);
  },
  action: async ({ pathParams }, req) => {
    const orderData = await getWCOrder(
      pathParams.id,
      req.headers.get("x-store-id") as string,
    );

    if (!orderData) {
      return NextResponse.json({ message: "Order not found" }, { status: 404 });
    }

    return NextResponse.json(orderData);
  },
  responses: {
    200: {
      description: "Order retrieved successfully",
      content: OrderDTO,
    },
    401: {
      description: "Unauthorized",
    },
    404: {
      description: "Order not found",
    },
    500: {
      description: "Error retrieving order",
    },
  },
  handleErrors: (errorType, issues) => handleApiErrors({ errorType, issues }),
});

Root Cause Analysis

The issue stems from Next.js 15's change in how route parameters are handled:

Next.js 15 expects:

context: { params: Promise<{ id: string }> }

But the library generates:

context: RouteHandlerContext<{ id: ZodString }>

Additional Context

• This affects all dynamic routes using defineRoute

Would you consider updating the library to support Next.js 15.5.0 ? This would be greatly appreciated as many projects are upgrading to the latest Next.js version.

Thank you for maintaining this useful library! 🙏

[btnalexandre]

Fixed with Next.js 15.5.1-canary.1, seems related to vercel/next.js#82842

I'm leaving the issue open for anyone else who might be looking for the same thing.

[omermecitoglu]

@btnalexandre thanks for the research. As you mentioned, I think it was fixed in next.js 15.5.2

[omermecitoglu]

Also for any of those who might face a similar problem while upgrading to 15.5, I want to share my experience

I noticed there was a type issue when I was building one of my services.

            Types of property 'params' are incompatible.
              Type 'Promise<{ id: string; }>' is not assignable to type 'Promise<{ id: number; }>'.
                Type '{ id: string; }' is not assignable to type '{ id: number; }'.
                  Types of property 'id' are incompatible.
                    Type 'string' is not assignable to type 'number'.

for this piece of code

    pathParams: z.object({
        id: z.number().describe("ID of the subscription"),
    }),

and I fixed it with coerce number

    pathParams: z.object({
        id: z.coerce.number<string>().describe("ID of the subscription"),
    }),