feat: initial href typing support

Author: bgub

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

@@ -141,12 +141,125 @@ function generateLayoutSlotMap(routesManifest: RouteTypesManifest): string {
   return slotMap
 }
 
+function generateRouteValidationTypes(
+  routesManifest: RouteTypesManifest
+): string {
+  const allRoutes = {
+    ...routesManifest.appRoutes,
+    ...routesManifest.pageRoutes,
+    ...routesManifest.layoutRoutes,
+  }
+
+  // Separate static and dynamic routes
+  const staticRoutes: string[] = []
+  const dynamicRoutes: string[] = []
+
+  for (const [route, routeInfo] of Object.entries(allRoutes)) {
+    const { groups } = routeInfo
+    const hasParams = Object.keys(groups).length > 0
+
+    if (hasParams) {
+      dynamicRoutes.push(route)
+    } else {
+      staticRoutes.push(route)
+    }
+  }
+
+  // Sort routes for consistent output
+  staticRoutes.sort()
+  dynamicRoutes.sort()
+
+  let result = `// Template literal types for route validation
+type SearchOrHash = \`?\${string}\` | \`#\${string}\`
+type WithProtocol = \`\${string}:\${string}\`
+type Suffix = '' | SearchOrHash
+
+type SafeSlug<S extends string> = S extends \`\${string}/\${string}\`
+  ? never
+  : S extends \`\${string}\${SearchOrHash}\`
+  ? never
+  : S extends ''
+  ? never
+  : S
+
+type CatchAllSlug<S extends string> = S extends \`\${string}\${SearchOrHash}\`
+  ? never
+  : S extends ''
+  ? never
+  : S
+
+type OptionalCatchAllSlug<S extends string> =
+  S extends \`\${string}\${SearchOrHash}\` ? never : S
+
+`
+
+  // Generate StaticRoutes
+  if (staticRoutes.length > 0) {
+    result += `type StaticRoutes = ${staticRoutes.map((route) => `\`${route}\``).join(' | ')}\n\n`
+  } else {
+    result += 'type StaticRoutes = never\n\n'
+  }
+
+  // Generate DynamicRoutes template
+  if (dynamicRoutes.length > 0) {
+    result += 'type DynamicRoutes<T extends string = string> = '
+    const dynamicTemplates: string[] = []
+
+    for (const route of dynamicRoutes) {
+      const routeInfo = allRoutes[route]
+      const { groups } = routeInfo
+
+      // Convert route pattern to template literal type
+      let template = route
+      for (const [key, group] of Object.entries(groups)) {
+        if (group.repeat) {
+          if (group.optional) {
+            // Optional catch-all: [[...param]]
+            template = template.replace(
+              `[[...${key}]]`,
+              `\${OptionalCatchAllSlug<T>}`
+            )
+          } else {
+            // Catch-all: [...param]
+            template = template.replace(`[...${key}]`, `\${CatchAllSlug<T>}`)
+          }
+        } else {
+          if (group.optional) {
+            // Optional param: [[param]]
+            template = template.replace(`[[${key}]]`, `\${SafeSlug<T>}`)
+          } else {
+            // Regular param: [param]
+            template = template.replace(`[${key}]`, `\${SafeSlug<T>}`)
+          }
+        }
+      }
+      dynamicTemplates.push(`\`${template}\``)
+    }
+
+    result += `${dynamicTemplates.join(' | ')}\n\n`
+  } else {
+    result += 'type DynamicRoutes<T extends string = string> = never\n\n'
+  }
+
+  result += `type ValidRoute<T extends string = string> = 
+  | StaticRoutes
+  | SearchOrHash
+  | WithProtocol
+  | \`\${StaticRoutes}\${SearchOrHash}\`
+  | (T extends \`\${DynamicRoutes<infer _>}\${Suffix}\` ? T : never)
+
+`
+
+  return result
+}
+
 export function generateRouteTypesFile(
   routesManifest: RouteTypesManifest
 ): string {
   const routeTypes = generateRouteTypes(routesManifest)
   const paramTypes = generateParamTypes(routesManifest)
   const layoutSlotMap = generateLayoutSlotMap(routesManifest)
+  const routeValidationTypes = generateRouteValidationTypes(routesManifest)
 
   return `// This file is generated automatically by Next.js
 // Do not edit this file manually
@@ -164,6 +277,7 @@ type LayoutChildren<P extends LayoutRoutes> = { children: React.ReactNode } & {
 }
 
 export type { AppRoutes, PageRoutes, LayoutRoutes, RedirectRoutes, RewriteRoutes }
+${routeValidationTypes}
 
 declare global {
   /**
@@ -208,7 +322,7 @@ type NeedsParams<R extends Routes> =
   keyof ParamsOf<R> extends never ? false : true;
 
 /**
- * Traditional \`href\` navigation.
+ * Traditional \`href\` navigation with route validation.
  *
  * @example
  * \`\`\`tsx
@@ -217,8 +331,8 @@ type NeedsParams<R extends Routes> =
  * <Link href={{ pathname: '/about', query: { tab: 'contact' } }}>About</Link>
  * \`\`\`
  */
-export type LinkPropsWithHref = LinkRestProps & {
-  href: string | UrlObject;
+export type LinkPropsWithHref<RouteInferType = string> = LinkRestProps & {
+  href: ValidRoute<RouteInferType> | UrlObject;
   path?: never;
   params?: never;
   searchParams?: never;
@@ -259,9 +373,9 @@ export type LinkPropsWithPath<T extends Routes> = LinkRestProps &
         href?: never;
       });
 
-export type LinkProps<RouteType extends Routes = Routes> =
-  | LinkPropsWithHref
-  | LinkPropsWithPath<RouteType>;
+export type LinkProps<RouteType extends string = string> =
+  | LinkPropsWithHref<RouteType>
+  | (RouteType extends Routes ? LinkPropsWithPath<RouteType> : never);
 
 declare module 'next/link' {
   /**
@@ -276,18 +390,61 @@ declare module 'next/link' {
    *
    * @example
    * \`\`\`tsx
-   * // href mode
+   * // href mode with route validation
    * <Link href="/about">About</Link>
+   * <Link href="/blog/my-post">Blog Post</Link>
    *
-   * // path mode
+   * // path mode with typed params
    * <Link path="/blog/[slug]" params={{ slug: 'my-post' }}>
    *   Blog
    * </Link>
    * \`\`\`
    */
-  export default function Link<RouteType extends Routes = Routes>(
+  export default function Link<RouteType extends string = string>(
     props: LinkProps<RouteType> & { children: React.ReactNode }
   ): JSX.Element;
 }
+
+declare module 'next/navigation' {
+  export * from 'next/dist/client/components/navigation.js'
+
+  import type { NavigateOptions, AppRouterInstance as OriginalAppRouterInstance } from 'next/dist/shared/lib/app-router-context.shared-runtime.js'
+  interface AppRouterInstance extends OriginalAppRouterInstance {
+    /**
+     * Navigate to the provided href.
+     * Pushes a new history entry.
+     */
+    push<RouteType extends Routes = Routes>(href: ValidRoute<RouteType>, options?: NavigateOptions): void
+    /**
+     * Navigate to the provided href.
+     * Replaces the current history entry.
+     */
+    replace<RouteType extends Routes = Routes>(href: ValidRoute<RouteType>, options?: NavigateOptions): void
+    /**
+     * Prefetch the provided href.
+     */
+    prefetch<RouteType extends Routes = Routes>(href: ValidRoute<RouteType>): void
+  }
+
+  export function useRouter(): AppRouterInstance;
+}
+
+declare module 'next/form' {
+  import type { FormProps as OriginalFormProps } from 'next/dist/client/form.js'
+
+  type FormRestProps = Omit<OriginalFormProps, 'action'>
+
+  export type FormProps<RouteInferType = string> = {
+    /**
+     * \`action\` can be either a \`string\` or a function.
+     * - If \`action\` is a string, it will be interpreted as a path or URL to navigate to when the form is submitted.
+     *   The path will be prefetched when the form becomes visible.
+     * - If \`action\` is a function, it will be called when the form is submitted. See the [React docs](https://react.dev/reference/react-dom/components/form#props) for more.
+     */
+    action: ValidRoute<RouteInferType> | ((formData: FormData) => void)
+  } & FormRestProps
+
+  export default function Form<RouteType = string>(props: FormProps<RouteType>): JSX.Element
+}
 `
 }

test/e2e/app-dir/typed-routes/app/dashboard/page.tsx

@@ -1,3 +1,11 @@
+import Link from 'next/link'
+
 export default function DashboardPage(props: PageProps<'/dashboard'>) {
-  return <div>Dashboard Home</div>
+  return (
+    <div>
+      <p>Dashboard Home</p>
+      <Link href="/shop/">Settings</Link>
+      <Link href="/about">About</Link>
+    </div>
+  )
 }

test/e2e/app-dir/typed-routes/app/dashboard/settings/page.tsx

@@ -1,9 +1,12 @@
+import Link from 'next/link'
+
 export default function DashboardSettingsPage(
   props: PageProps<'/dashboard/settings'>
 ) {
   return (
     <div>
       <h4>Dashboard Settings</h4>
+      <Link href="/dashboard?foo=bar">Dashboard</Link>
       <p>Main dashboard configuration settings.</p>
     </div>
   )