jsdocs

vercel · Feb 2, 2025 · 9de9c46 · 9de9c46
1 parent 58e1bd2
commit 9de9c46
Show file tree

Hide file tree

Showing 3 changed files with 377 additions and 212 deletions.
diff --git a/docs/01-app/04-api-reference/04-functions/generate-metadata.mdx b/docs/01-app/04-api-reference/04-functions/generate-metadata.mdx
@@ -664,6 +664,10 @@ export const metadata = {
 
 > **Deprecated**: The `themeColor` option in `metadata` is deprecated as of Next.js 14. Please use the [`viewport` configuration](/docs/app/api-reference/functions/generate-viewport) instead.
 
+### `colorScheme`
+
+> **Deprecated**: The `colorScheme` option in `metadata` is deprecated as of Next.js 14. Please use the [`viewport` configuration](/docs/app/api-reference/functions/generate-viewport) instead.
+
 ### `manifest`
 
 A web application manifest, as defined in the [Web Application Manifest specification](https://developer.mozilla.org/docs/Web/Manifest).

diff --git a/packages/next/src/client/app-dir/link.tsx b/packages/next/src/client/app-dir/link.tsx
@@ -33,79 +33,168 @@ type OptionalKeys<T> = {
 
 type InternalLinkProps = {
   /**
-   * The path or URL to navigate to. It can also be an object.
+   * **Required**. The path or URL to navigate to. It can also be an object (similar to `URL`).
    *
-   * @example https://nextjs.org/docs/api-reference/next/link#with-url-object
+   * @example
+   * ```tsx
+   * // Navigate to /dashboard:
+   * <Link href="/dashboard">Dashboard</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
+
   /**
-   * 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).
+   * @deprecated v10.0.0: `href` props pointing to a dynamic route are
+   * automatically resolved and no longer require the `as` prop.
    */
   as?: Url
+
   /**
-   * Replace the current `history` state instead of adding a new url into the stack.
+   * Replace the current `history` state instead of adding a new URL into the stack.
    *
    * @defaultValue `false`
+   *
+   * @example
+   * ```tsx
+   * <Link href="/about" replace>
+   *   About (replaces the history state)
+   * </Link>
+   * ```
    */
   replace?: boolean
+
   /**
-   * Whether to override the default scroll behavior
+   * Whether to override the default scroll behavior. If `true`, Next.js attempts to maintain
+   * the scroll position if the newly navigated page is still visible. If not, it scrolls to the top.
    *
-   * @example https://nextjs.org/docs/api-reference/next/link#disable-scrolling-to-the-top-of-the-page
+   * If `false`, Next.js will not modify the scroll behavior at all.
    *
    * @defaultValue `true`
+   *
+   * @example
+   * ```tsx
+   * <Link href="/dashboard" scroll={false}>
+   *   No auto scroll
+   * </Link>
+   * ```
    */
   scroll?: boolean
+
   /**
-   * Update the path of the current page without rerunning [`getStaticProps`](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-static-props), [`getServerSideProps`](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-server-side-props) or [`getInitialProps`](/docs/pages/api-reference/functions/get-initial-props).
+   * Update the path of the current page without rerunning data fetching methods
+   * like `getStaticProps`, `getServerSideProps`, or `getInitialProps`.
+   *
+   * @remarks
+   * `shallow` only applies to the Pages Router. For the App Router, see the
+   * [following documentation](https://nextjs.org/docs/app/building-your-application/routing/linking-and-navigating#using-the-native-history-api).
    *
    * @defaultValue `false`
+   *
+   * @example
+   * ```tsx
+   * <Link href="/blog" shallow>
+   *   Shallow navigation
+   * </Link>
+   * ```
    */
   shallow?: boolean
+
   /**
-   * Forces `Link` to send the `href` property to its child.
+   * Forces `Link` to pass its `href` to the child component. Useful if the child is a custom
+   * component that wraps an `<a>` tag, or if you're using certain styling libraries.
    *
    * @defaultValue `false`
+   *
+   * @example
+   * ```tsx
+   * <Link href="/dashboard" passHref>
+   *   <MyStyledAnchor>Dashboard</MyStyledAnchor>
+   * </Link>
+   * ```
    */
   passHref?: boolean
+
   /**
    * Prefetch the page in the background.
    * Any `<Link />` that is in the viewport (initially or through scroll) will be prefetched.
-   * Prefetch can be disabled by passing `prefetch={false}`. Prefetching is only enabled in production.
+   * Prefetch can be disabled by passing `prefetch={false}`.
+   *
+   * @remarks
+   * Prefetching is only enabled in production.
+   *
+   * - In the **App Router**:
+   *   - `null` (default): Prefetch behavior depends on static vs dynamic routes:
+   *     - Static routes: fully prefetched
+   *     - Dynamic routes: partial prefetch to the nearest segment with a `loading.js`
+   *   - `true`: Always prefetch the full route and data.
+   *   - `false`: Disable prefetching on both viewport and hover.
+   * - In the **Pages Router**:
+   *   - `true` (default): Prefetches the route and data in the background on viewport or hover.
+   *   - `false`: Prefetch only on hover, not on viewport.
    *
-   * In App Router:
-   * - `null` (default): For statically generated pages, this will prefetch the full React Server Component data. For dynamic pages, this will prefetch up to the nearest route segment with a [`loading.js`](https://nextjs.org/docs/app/api-reference/file-conventions/loading) file. If there is no loading file, it will not fetch the full tree to avoid fetching too much data.
-   * - `true`: This will prefetch the full React Server Component data for all route segments, regardless of whether they contain a segment with `loading.js`.
-   * - `false`: This will not prefetch any data, even on hover.
+   * @defaultValue `true` (Pages Router) or `null` (App Router)
    *
-   * In Pages Router:
-   * - `true` (default): The full route & its data will be prefetched.
-   * - `false`: Prefetching will not happen when entering the viewport, but will still happen on hover.
-   * @defaultValue `true` (pages router) or `null` (app router)
+   * @example
+   * ```tsx
+   * <Link href="/dashboard" prefetch={false}>
+   *   Dashboard
+   * </Link>
+   * ```
    */
   prefetch?: boolean | null
+
   /**
-   * The active locale is automatically prepended. `locale` allows for providing a different locale.
-   * When `false` `href` has to include the locale as the default behavior is disabled.
-   * Note: This is only available in the Pages Router.
+   * The active locale is automatically prepended in the Pages Router. `locale` allows for providing
+   * a different locale, or can be set to `false` to opt out of automatic locale behavior.
+   *
+   * @remarks
+   * Note: locale only applies in the Pages Router and is ignored in the App Router.
+   *
+   * @example
+   * ```tsx
+   * // Use the 'fr' locale:
+   * <Link href="/about" locale="fr">
+   *   About (French)
+   * </Link>
+   *
+   * // Disable locale prefix:
+   * <Link href="/about" locale={false}>
+   *   About (no locale prefix)
+   * </Link>
+   * ```
    */
   locale?: string | false
+
   /**
-   * Enable legacy link behavior.
+   * Enable legacy link behavior, requiring an `<a>` tag to wrap the child content
+   * if the child is a string or number.
+   *
    * @defaultValue `false`
    * @see https://github.com/vercel/next.js/commit/489e65ed98544e69b0afd7e0cfc3f9f6c2b803b7
    */
   legacyBehavior?: boolean
+
   /**
-   * Optional event handler for when the mouse pointer is moved onto Link
+   * Optional event handler for when the mouse pointer is moved onto the `<Link>`.
    */
   onMouseEnter?: React.MouseEventHandler<HTMLAnchorElement>
+
   /**
-   * Optional event handler for when Link is touched.
+   * Optional event handler for when the `<Link>` is touched.
    */
   onTouchStart?: React.TouchEventHandler<HTMLAnchorElement>
+
   /**
-   * Optional event handler for when Link is clicked.
+   * Optional event handler for when the `<Link>` is clicked.
    */
   onClick?: React.MouseEventHandler<HTMLAnchorElement>
 }
@@ -400,12 +489,14 @@ function formatStringOrUrl(urlObjOrString: UrlObject | string): string {
 }
 
 /**
- * A React component that extends the HTML `<a>` element to provide [prefetching](https://nextjs.org/docs/app/building-your-application/routing/linking-and-navigating#2-prefetching)
- * and client-side navigation between routes.
+ * A React component that extends the HTML `<a>` element to provide
+ * [prefetching](https://nextjs.org/docs/app/building-your-application/routing/linking-and-navigating#2-prefetching)
+ * and client-side navigation. This is the primary way to navigate between routes in Next.js.
  *
- * It is the primary way to navigate between routes in Next.js.
+ * @remarks
+ * - Prefetching is only enabled in production.
  *
- * Read more: [Next.js docs: `<Link>`](https://nextjs.org/docs/app/api-reference/components/link)
+ * @see https://nextjs.org/docs/app/api-reference/components/link
  */
 const Link = React.forwardRef<HTMLAnchorElement, LinkPropsReal>(
   function LinkComponent(props, forwardedRef) {