Implement Route type for router APIs

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

@@ -432,7 +432,32 @@ declare module 'next/link' {
   }
 
   export default function Link<RouteType>(props: LinkProps<RouteType>): JSX.Element
-}`
+}
+
+declare module 'next/navigation' {
+  export * from 'next/dist/client/components/navigation'
+
+  import type { NavigateOptions, AppRouterInstance as OriginalAppRouterInstance } from 'next/dist/shared/lib/app-router-context'
+  interface AppRouterInstance extends OriginalAppRouterInstance {
+    /**
+     * Navigate to the provided href.
+     * Pushes a new history entry.
+     */
+    push<RouteType>(href: __next_route_internal_types__.RouteImpl<RouteType>, options?: NavigateOptions): void
+    /**
+     * Navigate to the provided href.
+     * Replaces the current history entry.
+     */
+    replace<RouteType>(href: __next_route_internal_types__.RouteImpl<RouteType>, options?: NavigateOptions): void
+    /**
+     * Prefetch the provided href.
+     */
+    prefetch<RouteType>(href: __next_route_internal_types__.RouteImpl<RouteType>): void
+  }
+
+  export declare function useRouter(): AppRouterInstance;
+}
+`
 }
 
 const appTypesBasePath = path.join('types', 'app')

packages/next/src/shared/lib/app-router-context.ts

@@ -63,7 +63,8 @@ export type CacheNode =
        */
       parallelRoutes: Map<string, ChildSegmentMap>
     }
-interface NavigateOptions {
+
+export interface NavigateOptions {
   forceOptimisticNavigation?: boolean
 }
 

test/integration/app-types/app-types.test.js

@@ -44,6 +44,21 @@ describe('app type checking', () => {
       )
     })
 
+    it('should generate route types correctly and report router API errors', async () => {
+      // Make sure all errors were reported and other links passed type checking
+      const errorLines = [
+        ...errors.matchAll(
+          /\.\/src\/app\/type-checks\/router\/page\.tsx:(\d+):/g
+        ),
+      ].map(([, line]) => +line)
+
+      const ST = 11
+      const ED = 13
+      expect(errorLines).toEqual(
+        Array.from({ length: ED - ST + 1 }, (_, i) => i + ST)
+      )
+    })
+
     it('should type check invalid entry exports', () => {
       // Can't export arbitrary things.
       expect(errors).toContain(`"foo" is not a valid Page export field.`)

test/integration/app-types/src/app/type-checks/router/page.tsx

@@ -0,0 +1,25 @@
+'use client'
+
+import { useRouter } from 'next/navigation'
+import type { Route } from 'next'
+
+export default function Page() {
+  const router = useRouter()
+
+  function test() {
+    // Invalid routes:
+    router.push('/wrong-link')
+    router.push('/blog/a?1/b')
+    router.push(`/blog/${'a/b/c'}`)
+
+    // Correctly typed:
+    router.push('/dashboard/another')
+    router.prefetch('/about')
+    router.push('/redirect')
+    router.push(`/blog/${'a/b'}`)
+    router.push('/invalid' as Route)
+    router.back()
+  }
+
+  return <div onClick={test} />
+}