[backport] fix: validation return types of pages API routes (#83069) (#83580)

I don't think this fix ever got backported to Next 15.5!

@huozhi @ijjk @ztanner

Author: bgub

packages/next/src/server/lib/router-utils/typegen.ts

@@ -566,7 +566,7 @@ export function generateValidatorFile(
 
   if (pagesApiRouteValidations) {
     typeDefinitions += `type ApiRouteConfig = {
-  default: (req: any, res: any) => Promise<Response | void> | Response | void
+  default: (req: any, res: any) => ReturnType<NextApiHandler>
   config?: {
     api?: {
       bodyParser?: boolean | { sizeLimit?: string }
@@ -612,18 +612,25 @@ export function generateValidatorFile(
     ? "import type { NextRequest } from 'next/server.js'\n"
     : ''
 
-  // Only import metadata types if there are App Router pages or layouts that might use them
-  const metadataImport =
-    appPageValidations || layoutValidations
-      ? 'import type { ResolvingMetadata, ResolvingViewport } from "next/dist/lib/metadata/types/metadata-interface.js"\n'
+  // Conditionally import types from next/types, merged into a single statement
+  const nextTypes: string[] = []
+  if (pagesApiRouteValidations) {
+    nextTypes.push('NextApiHandler')
+  }
+  if (appPageValidations || layoutValidations) {
+    nextTypes.push('ResolvingMetadata', 'ResolvingViewport')
+  }
+  const nextTypesImport =
+    nextTypes.length > 0
+      ? `import type { ${nextTypes.join(', ')} } from "next/types.js"\n`
       : ''
 
   return `// This file is generated automatically by Next.js
 // Do not edit this file manually
 // This file validates that all pages and layouts export the correct types
 
 ${routeImportStatement}
-${metadataImport}${nextRequestImport}
+${nextTypesImport}${nextRequestImport}
 ${typeDefinitions}
 ${appPageValidations}
 

test/e2e/app-dir/typed-routes-validator/pages/api/test-route.ts

@@ -1,12 +1,11 @@
-import type { NextApiRequest, NextApiResponse } from 'next/types'
+import type { NextApiHandler } from 'next/types'
 
 type ResponseData = {
   message: string
 }
 
-export default function handler(
-  req: NextApiRequest,
-  res: NextApiResponse<ResponseData>
-) {
+const handler: NextApiHandler<ResponseData> = (req, res) => {
   res.status(200).json({ message: 'Hello from Next.js!' })
 }
+
+export default handler