feat: fully working typed links

Author: bgub

packages/next/errors.json

@@ -720,5 +720,10 @@
   "719": "Failed to get source map for '%s'. This is a bug in Next.js",
   "720": "A client prerender store should not be used for a route handler.",
   "721": "Render in Browser",
-  "722": "Unable to match pathname to a dynamic route"
-}
+  "722": "Unable to match pathname to a dynamic route",
+  "723": "Dynamic href \\`%s\\` found in <Link> while using the \\`/app\\` router, this is not supported. Instead, you should use \\`path\\` and \\`params\\` props. Read more: https://nextjs.org/docs/messages/app-dir-dynamic-href",
+  "724": "Invalid <Link> with neither `href` nor `path` prop. You must provide exactly one of these props.",
+  "725": "Invalid <Link> with `params` prop but no `path` prop. `params` can only be used with `path`.",
+  "726": "Invalid <Link> with both `href` and `path` props. You must use exactly one of these props.",
+  "727": "Invalid <Link> with `searchParams` prop but no `path` prop. `searchParams` can only be used with `path`."
+}

packages/next/src/client/app-dir/link.tsx

@@ -30,7 +30,7 @@ type OptionalKeys<T> = {
 
 type OnNavigateEventHandler = (event: { preventDefault: () => void }) => void
 
-type InternalLinkPropsBase = {
+export type InternalLinkProps = {
   /**
    * @deprecated v10.0.0: `href` props pointing to a dynamic route are
    * automatically resolved and no longer require the `as` prop.
@@ -190,71 +190,64 @@ type InternalLinkPropsBase = {
   onNavigate?: OnNavigateEventHandler
 }
 
-type InternalLinkProps = InternalLinkPropsBase &
-  (
-    | {
-        /**
-         * **Required**. The path or URL to navigate to. It can also be an object (similar to `URL`).
-         * Accepts any string for external URLs and backwards compatibility.
-         *
-         * @example
-         * ```tsx
-         * // Navigate to /dashboard:
-         * <Link href="/dashboard">Dashboard</Link>
-         *
-         * // External URL:
-         * <Link href="https://example.com">External Site</Link>
-         *
-         * // Navigate to /about?name=test:
-         * <Link href={{ pathname: '/about', query: { name: 'test' } }}>
-         *   About
-         * </Link>
-         * ```
-         *
-         * @remarks
-         * - For external URLs, use a fully qualified URL such as `https://...`.
-         * - In the App Router, dynamic routes must not include bracketed segments in `href`.
-         */
-        href: Url
-
-        /**
-         * These props are not available when using href
-         */
-        path?: never
-        params?: never
-        searchParams?: never
-      }
-    | {
-        /**
-         * The href property is not available when using path
-         */
-        href?: never
-
-        /**
-         * The route path template for typed links (e.g., '/blog/[slug]')
-         */
-        path: string
-
-        /**
-         * Parameters for dynamic route segments (only available with path)
-         */
-        params?: Record<string, string | string[]>
-
-        /**
-         * Search parameters to append to the URL (only available with path)
-         */
-        searchParams?: Record<string, string | string[]>
-      }
-  )
+export type HrefProps = {
+  /**
+   * **Required**. The path or URL to navigate to. It can also be an object (similar to `URL`).
+   * Accepts any string for external URLs and backwards compatibility.
+   *
+   * @example
+   * ```tsx
+   * // Navigate to /dashboard:
+   * <Link href="/dashboard">Dashboard</Link>
+   *
+   * // External URL:
+   * <Link href="https://example.com">External Site</Link>
+   *
+   * // Navigate to /about?name=test:
+   * <Link href={{ pathname: '/about', query: { name: 'test' } }}>
+   *   About
+   * </Link>
+   * ```
+   *
+   * @remarks
+   * - For external URLs, use a fully qualified URL such as `https://...`.
+   * - In the App Router, dynamic routes must not include bracketed segments in `href`.
+   */
+  href: Url
+
+  /**
+   * These props are not available when using href
+   */
+  path?: never
+  params?: never
+  searchParams?: never
+}
+
+type PathProps = {
+  /**
+   * The href property is not available when using path
+   */
+  href?: never
+  /**
+   * The route path template for typed links (e.g., '/blog/[slug]')
+   */
+  path: string
+  /**
+   * Parameters for dynamic route segments (only available with path)
+   */
+  params?: Record<string, string | string[]>
+  /**
+   * Search parameters to append to the URL (only available with path)
+   */
+  searchParams?: Record<string, string | string[]>
+}
+
+export type LinkProps = InternalLinkProps & (HrefProps | PathProps)
 
 // TODO-APP: Include the full set of Anchor props
 // adding this to the publicly exported type currently breaks existing apps
 
-// `RouteInferType` is a stub here to avoid breaking `typedRoutes` when the type
-// isn't generated yet. It will be replaced when the webpack plugin runs.
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export type LinkProps<RouteInferType = any> = InternalLinkProps
-type LinkPropsOptional = OptionalKeys<Omit<InternalLinkProps, 'locale'>>
+type LinkPropsOptional = OptionalKeys<Omit<LinkProps, 'locale'>>
 
 function isModifiedEvent(event: React.MouseEvent): boolean {
   const eventTarget = event.currentTarget as HTMLAnchorElement | SVGAElement
@@ -379,7 +372,7 @@ export default function LinkComponent(
     params,
     searchParams,
     ...restProps
-  } = props as any // TypeScript discriminated union handled at type level
+  } = props
 
   children = childrenProp
 
@@ -588,7 +581,7 @@ export default function LinkComponent(
 
         if (hasDynamicSegment) {
           throw new Error(
-            `Dynamic href \`${href}\` found in <Link> while using the \`/app\` router, this is not supported. Read more: https://nextjs.org/docs/messages/app-dir-dynamic-href`
+            `Dynamic href \`${href}\` found in <Link> while using the \`/app\` router, this is not supported. Instead, you should use \`path\` and \`params\` props. Read more: https://nextjs.org/docs/messages/app-dir-dynamic-href`
           )
         }
       }

packages/next/src/client/link.tsx

@@ -24,7 +24,7 @@ import { constructHref } from '../shared/lib/router/utils/construct-href'
 type Url = string | UrlObject
 type OnNavigateEventHandler = (event: { preventDefault: () => void }) => void
 
-type InternalLinkPropsBase = {
+export type InternalLinkProps = {
   /**
    * Optional decorator for the path that will be shown in the browser URL bar. Before Next.js 9.5.3 this was used for dynamic routes, check our [previous docs](https://github.com/vercel/next.js/blob/v9.5.2/docs/api-reference/next/link.md#dynamic-routes) to see how it worked. Note: when this path differs from the one provided in `href` the previous `href`/`as` behavior is used as shown in the [previous docs](https://github.com/vercel/next.js/blob/v9.5.2/docs/api-reference/next/link.md#dynamic-routes).
    */
@@ -102,54 +102,63 @@ type InternalLinkPropsBase = {
   onNavigate?: OnNavigateEventHandler
 }
 
-type InternalLinkProps = InternalLinkPropsBase &
-  (
-    | {
-        /**
-         * The path or URL to navigate to. It can also be an object.
-         * Accepts any string for external URLs and backwards compatibility.
-         *
-         * @example https://nextjs.org/docs/api-reference/next/link#with-url-object
-         */
-        href: Url
-        /**
-         * These props are not available when using href
-         */
-        path?: never
-        params?: never
-        searchParams?: never
-      }
-    | {
-        /**
-         * The href property is not available when using path
-         */
-        href?: never
-        /**
-         * The route path template for typed links (e.g., '/blog/[slug]')
-         */
-        path: string
-        /**
-         * Parameters for dynamic route segments (only available with path)
-         */
-        params?: Record<string, string | string[]>
-        /**
-         * Search parameters to append to the URL (only available with path)
-         */
-        searchParams?: Record<string, string | string[]>
-      }
-  )
+export type HrefProps = {
+  /**
+   * **Required**. The path or URL to navigate to. It can also be an object (similar to `URL`).
+   * Accepts any string for external URLs and backwards compatibility.
+   *
+   * @example
+   * ```tsx
+   * // Navigate to /dashboard:
+   * <Link href="/dashboard">Dashboard</Link>
+   *
+   * // External URL:
+   * <Link href="https://example.com">External Site</Link>
+   *
+   * // Navigate to /about?name=test:
+   * <Link href={{ pathname: '/about', query: { name: 'test' } }}>
+   *   About
+   * </Link>
+   * ```
+   *
+   * @remarks
+   * - For external URLs, use a fully qualified URL such as `https://...`.
+   * - In the App Router, dynamic routes must not include bracketed segments in `href`.
+   */
+  href: Url
+
+  /**
+   * These props are not available when using href
+   */
+  path?: never
+  params?: never
+  searchParams?: never
+}
+
+type PathProps = {
+  /**
+   * The href property is not available when using path
+   */
+  href?: never
+  /**
+   * The route path template for typed links (e.g., '/blog/[slug]')
+   */
+  path: string
+  /**
+   * Parameters for dynamic route segments (only available with path)
+   */
+  params?: Record<string, string | string[]>
+  /**
+   * Search parameters to append to the URL (only available with path)
+   */
+  searchParams?: Record<string, string | string[]>
+}
+
+export type LinkProps = InternalLinkProps & (HrefProps | PathProps)
 
 // TODO-APP: Include the full set of Anchor props
 // adding this to the publicly exported type currently breaks existing apps
 
-// `RouteInferType` is a stub here to avoid breaking `typedRoutes` when the type
-// isn't generated yet. It will be replaced when the webpack plugin runs.
-// WARNING: This should be an interface to prevent TypeScript from inlining it
-// in declarations of libraries dependending on Next.js.
-// Not trivial to reproduce so only convert to an interface when needed.
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export type LinkProps<RouteInferType = any> = InternalLinkProps
-
 const prefetched = new Set<string>()
 
 type PrefetchOptions = RouterPrefetchOptions & {