Feat(next-types-plugin): added support for Route Handlers

packages/next/src/build/webpack/plugins/next-types-plugin.ts

@@ -1,17 +1,19 @@
 import type { Rewrite, Redirect } from '../../../lib/load-custom-routes'
 import type { Token } from 'next/dist/compiled/path-to-regexp'
 
-import path from 'path'
-import { promises as fs } from 'fs'
-
+import fs from 'fs/promises'
 import { webpack, sources } from 'next/dist/compiled/webpack/webpack'
 import { parse } from 'next/dist/compiled/path-to-regexp'
+import path from 'path'
+
 import { WEBPACK_LAYERS } from '../../../lib/constants'
+import { denormalizePagePath } from '../../../shared/lib/page-path/denormalize-page-path'
+import { ensureLeadingSlash } from '../../../shared/lib/page-path/ensure-leading-slash'
+import { normalizePathSep } from '../../../shared/lib/page-path/normalize-path-sep'
+import { HTTP_METHODS } from '../../../server/web/http'
 import { isDynamicRoute } from '../../../shared/lib/router/utils'
 import { normalizeAppPath } from '../../../shared/lib/router/utils/app-paths'
-import { denormalizePagePath } from '../../../shared/lib/page-path/denormalize-page-path'
 import { getPageFromPath } from '../../entries'
-import { ensureLeadingSlash } from '../../../shared/lib/page-path/ensure-leading-slash'
 
 const PLUGIN_NAME = 'NextTypesPlugin'
 
@@ -37,19 +39,24 @@ function createTypeGuardFile(
   fullPath: string,
   relativePath: string,
   options: {
-    type: 'layout' | 'page'
+    type: 'layout' | 'page' | 'route'
     slots?: string[]
   }
 ) {
   return `// File: ${fullPath}
 import * as entry from '${relativePath}'
 import type { ResolvingMetadata } from 'next/dist/lib/metadata/types/metadata-interface'
+import type { NextRequest } from 'next/server'
 
 type TEntry = typeof entry
 
 // Check that the entry is a valid entry
 checkFields<Diff<{
-  default: Function
+  ${
+    options.type === 'route'
+      ? HTTP_METHODS.map((method) => `${method}?: Function`).join('\n  ')
+      : 'default: Function'
+  }
   config?: {}
   generateStaticParams?: Function
   revalidate?: RevalidateRange<TEntry> | false
@@ -58,18 +65,64 @@ checkFields<Diff<{
   fetchCache?: 'auto' | 'force-no-store' | 'only-no-store' | 'default-no-store' | 'default-cache' | 'only-cache' | 'force-cache'
   preferredRegion?: 'auto' | 'home' | 'edge'
   ${
-    options.type === 'page'
+    options.type === 'page' || options.type === 'route'
       ? "runtime?: 'nodejs' | 'experimental-edge' | 'edge'"
       : ''
   }
+  ${
+    options.type === 'route'
+      ? ''
+      : `
   metadata?: any
   generateMetadata?: Function
+  `
+  }
 }, TEntry, ''>>()
 
-// Check the prop type of the entry function
+${
+  options.type === 'route'
+    ? `// Check the prop type of the entry function
+${HTTP_METHODS.map(
+  (method) => `
+if ('${method}' in entry) {
+  checkFields<
+    Diff<
+      {
+        __tag__: '${method}',
+        __param_position__: string,
+        __param_type__: Request | NextRequest
+      },
+      {
+        __tag__: '${method}',
+        __param_position__: 'first',
+        __param_type__: FirstArg<MaybeField<TEntry, '${method}'>>
+      },
+      '${method}'
+    >
+  >();
+  checkFields<
+    Diff<
+      {
+        __tag__: '${method}',
+        __param_position__: string,
+        __param_type__: PageParams
+      },
+      {
+        __tag__: '${method}',
+        __param_position__: 'second',
+        __param_type__: SecondArg<MaybeField<TEntry, '${method}'>>
+      },
+      '${method}'
+    >
+  >();
+}
+`
+).join('')}
+`
+    : `// Check the prop type of the entry function
 checkFields<Diff<${
-    options.type === 'page' ? 'PageProps' : 'LayoutProps'
-  }, FirstArg<TEntry['default']>, 'default'>>()
+        options.type === 'page' ? 'PageProps' : 'LayoutProps'
+      }, FirstArg<TEntry['default']>, 'default'>>()
 
 // Check the arguments and return type of the generateMetadata function
 if ('generateMetadata' in entry) {
@@ -78,13 +131,14 @@ if ('generateMetadata' in entry) {
   }, FirstArg<MaybeField<TEntry, 'generateMetadata'>>, 'generateMetadata'>>()
   checkFields<Diff<ResolvingMetadata, SecondArg<MaybeField<TEntry, 'generateMetadata'>>, 'generateMetadata'>>()
 }
-
+`
+}
 // Check the arguments and return type of the generateStaticParams function
 if ('generateStaticParams' in entry) {
   checkFields<Diff<{ params: PageParams }, FirstArg<MaybeField<TEntry, 'generateStaticParams'>>, 'generateStaticParams'>>()
   checkFields<Diff<{ __tag__: 'generateStaticParams', __return_type__: any[] | Promise<any[]> }, { __tag__: 'generateStaticParams', __return_type__: ReturnType<MaybeField<TEntry, 'generateStaticParams'>> }>>()
 }
-  
+
 type PageParams = any
 export interface PageProps {
   params?: any
@@ -341,7 +395,7 @@ declare namespace __next_route_internal_types__ {
       // This keeps autocompletion working for static routes.
       '| StaticRoutes'
     }
-    | \`\${StaticRoutes}\${Suffix}\`
+    | \`\${StaticRoutes}\${SearchOrHash}\`
     | (T extends \`\${DynamicRoutes<infer _>}\${Suffix}\` ? T : never)
     `
   }
@@ -416,8 +470,8 @@ export class NextTypesPlugin {
       return
     }
 
-    // Filter out non-page files in app dir
-    if (isApp && !/[/\\]page\.[^.]+$/.test(filePath)) {
+    // Filter out non-page and non-route files in app dir
+    if (isApp && !/[/\\](?:page|route)\.[^.]+$/.test(filePath)) {
       return
     }
 
@@ -474,11 +528,12 @@ export class NextTypesPlugin {
 
       const IS_LAYOUT = /[/\\]layout\.[^./\\]+$/.test(mod.resource)
       const IS_PAGE = !IS_LAYOUT && /[/\\]page\.[^.]+$/.test(mod.resource)
+      const IS_ROUTE = !IS_PAGE && /[/\\]route\.[^.]+$/.test(mod.resource)
       const relativePathToApp = path.relative(this.appDir, mod.resource)
       const relativePathToRoot = path.relative(this.dir, mod.resource)
 
       if (!this.dev) {
-        if (IS_PAGE) {
+        if (IS_PAGE || IS_ROUTE) {
           this.collectPage(mod.resource)
         }
       }
@@ -495,7 +550,7 @@ export class NextTypesPlugin {
           relativePathToRoot.replace(/\.(js|jsx|ts|tsx|mjs)$/, '')
         )
         .replace(/\\/g, '/')
-      const assetPath = assetDirRelative + '/' + typePath.replace(/\\/g, '/')
+      const assetPath = assetDirRelative + '/' + normalizePathSep(typePath)
 
       if (IS_LAYOUT) {
         const slots = await collectNamedSlots(mod.resource)
@@ -511,6 +566,12 @@ export class NextTypesPlugin {
             type: 'page',
           })
         )
+      } else if (IS_ROUTE) {
+        assets[assetPath] = new sources.RawSource(
+          createTypeGuardFile(mod.resource, relativeImportPath, {
+            type: 'route',
+          })
+        )
       }
     }
 
@@ -536,10 +597,14 @@ export class NextTypesPlugin {
             chunkGroup.chunks.forEach((chunk) => {
               if (!chunk.name) return
 
-              // Here we only track page chunks.
+              // Here we only track page and route chunks.
               if (
                 !chunk.name.startsWith('pages/') &&
-                !(chunk.name.startsWith('app/') && chunk.name.endsWith('/page'))
+                !(
+                  chunk.name.startsWith('app/') &&
+                  (chunk.name.endsWith('/page') ||
+                    chunk.name.endsWith('/route'))
+                )
               ) {
                 return
               }
@@ -575,7 +640,7 @@ export class NextTypesPlugin {
 
             const linkTypePath = path.join('types', 'link.d.ts')
             const assetPath =
-              assetDirRelative + '/' + linkTypePath.replace(/\\/g, '/')
+              assetDirRelative + '/' + normalizePathSep(linkTypePath)
             assets[assetPath] = new sources.RawSource(
               createRouteDefinitions()
             ) as unknown as webpack.sources.RawSource

packages/next/src/lib/typescript/diagnosticFormatter.ts

@@ -73,7 +73,11 @@ function getFormattedLayoutAndPageDiagnosticMessageText(
   const messageText = message.messageText
 
   if (typeof messageText === 'string') {
-    const type = /page\.[^.]+$/.test(relativeSourceFilepath) ? 'Page' : 'Layout'
+    const type = /page\.[^.]+$/.test(relativeSourceFilepath)
+      ? 'Page'
+      : /route\.[^.]+$/.test(relativeSourceFilepath)
+      ? 'Route'
+      : 'Layout'
 
     // Reference of error codes:
     // https://github.com/Microsoft/TypeScript/blob/main/src/compiler/diagnosticMessages.json
@@ -212,6 +216,52 @@ function getFormattedLayoutAndPageDiagnosticMessageText(
           return main
         }
 
+        function processNextItems(
+          indent: number,
+          next?: import('typescript').DiagnosticMessageChain[]
+        ) {
+          if (!next) return ''
+
+          let result = ''
+
+          for (const item of next) {
+            switch (item.code) {
+              case 2322:
+                const types = item.messageText.match(
+                  /Type '(.+)' is not assignable to type '(.+)'./
+                )
+                if (types) {
+                  result += '\n' + ' '.repeat(indent * 2)
+                  result += `Expected "${chalk.bold(
+                    types[2]
+                  )}", got "${chalk.bold(types[1])}".`
+                }
+                break
+              default:
+            }
+
+            result += processNextItems(indent + 1, item.next)
+          }
+
+          return result
+        }
+
+        const invalidParamFn = messageText.match(
+          /Type '{ __tag__: (.+); __param_position__: "(.*)"; __param_type__: (.+); }' does not satisfy/
+        )
+        if (invalidParamFn) {
+          let main = `${type} "${chalk.bold(
+            relativeSourceFilepath
+          )}" has an invalid ${invalidParamFn[1]} export:\n  Type "${chalk.bold(
+            invalidParamFn[3]
+          )}" is not a valid type for the function's ${
+            invalidParamFn[2]
+          } argument.`
+
+          if ('next' in message) main += processNextItems(1, message.next)
+          return main
+        }
+
         const invalidExportFnReturn = messageText.match(
           /Type '{ __tag__: "(.+)"; __return_type__: (.+); }' does not satisfy/
         )
@@ -221,33 +271,8 @@ function getFormattedLayoutAndPageDiagnosticMessageText(
           )}" has an invalid export:\n  "${chalk.bold(
             invalidExportFnReturn[2]
           )}" is not a valid ${invalidExportFnReturn[1]} return type:`
-          function processNext(
-            indent: number,
-            next?: import('typescript').DiagnosticMessageChain[]
-          ) {
-            if (!next) return
 
-            for (const item of next) {
-              switch (item.code) {
-                case 2322:
-                  const types = item.messageText.match(
-                    /Type '(.+)' is not assignable to type '(.+)'./
-                  )
-                  if (types) {
-                    main += '\n' + ' '.repeat(indent * 2)
-                    main += `Expected "${chalk.bold(
-                      types[2]
-                    )}", got "${chalk.bold(types[1])}".`
-                  }
-                  break
-                default:
-              }
-
-              processNext(indent + 1, item.next)
-            }
-          }
-
-          if ('next' in message) processNext(1, message.next)
+          if ('next' in message) main += processNextItems(1, message.next)
           return main
         }
 

test/e2e/app-dir/app-routes/app-custom-routes.test.ts

@@ -1,18 +1,35 @@
 import { createNextDescribe } from 'e2e-utils'
+import fs from 'fs-extra'
+import { check } from 'next-test-utils'
+import path from 'path'
+import { Readable } from 'stream'
+
 import {
   withRequestMeta,
   getRequestMeta,
   cookieWithRequestMeta,
 } from './helpers'
-import { Readable } from 'stream'
-import { check } from 'next-test-utils'
 
 createNextDescribe(
   'app-custom-routes',
   {
     files: __dirname,
   },
-  ({ next, isNextDev, isNextStart }) => {
+  ({ next, isNextDeploy, isNextDev, isNextStart }) => {
+    beforeAll(async () => {
+      if (isNextDev) {
+        await fs.move(
+          path.join(next.testDir, 'app/_lowercase'),
+          path.join(next.testDir, 'app/lowercase'),
+          { overwrite: true }
+        )
+        await fs.move(
+          path.join(next.testDir, 'app/_default'),
+          path.join(next.testDir, 'app/default'),
+          { overwrite: true }
+        )
+      }
+    })
     describe('works with api prefix correctly', () => {
       it('statically generates correctly with no dynamic usage', async () => {
         if (isNextStart) {
@@ -188,7 +205,7 @@ createNextDescribe(
 
     describe('body', () => {
       // we can't stream a body to a function currently only stream response
-      if (!(global as any).isNextDeploy) {
+      if (!isNextDeploy) {
         it('can handle handle a streaming request and streaming response', async () => {
           const body = new Array(10).fill(JSON.stringify({ ping: 'pong' }))
           let index = 0
@@ -257,7 +274,7 @@ createNextDescribe(
       })
 
       // we can't stream a body to a function currently only stream response
-      if (!(global as any).isNextDeploy) {
+      if (!isNextDeploy) {
         it('can read a streamed JSON encoded body', async () => {
           const body = { ping: 'pong' }
           const encoded = JSON.stringify(body)
@@ -444,7 +461,7 @@ createNextDescribe(
         expect(res.status).toEqual(500)
         expect(await res.text()).toBeEmpty()
 
-        if (!(global as any).isNextDeploy) {
+        if (!isNextDeploy) {
           await check(() => {
             expect(next.cliOutput).toContain(error)
             return 'yes'

test/e2e/app-dir/app-routes/handlers/hello.ts

@@ -1,7 +1,7 @@
 import { type NextRequest } from 'next/server'
 import { withRequestMeta } from '../helpers'
 
-export const helloHandler = async (
+const helloHandler = async (
   request: NextRequest,
   { params }: { params?: Record<string, string | string[]> }
 ): Promise<Response> => {