[Link] Add prefetch="auto" option

Adds a "auto" as a valid value for the `<Link>` component's prefetch
prop. It acts as an alias for the default behavior, i.e. same as no
prefetch prop at all.

---

A common source of confusion is the difference between `<Link>`, `<Link
prefetch={null}>`, and `<Link prefetch={boolean}>`:

- `prefetch={true}` → dynamically prefetch the whole page
- `prefetch={false}` → disable prefetching entirely
- no prop, `prefetch={null}`, `prefetch={undefined}` → default behavior

If you want to conditionally opt into dynamic prefetching, you have to
write something like this:

```
<Link prefetch={shouldDynamicallyPrefetch ? true : null}>
```

After this PR, you can do this instead:

```
<Link prefetch={shouldDynamicallyPrefetch ? true : 'auto'}>
```

It's still a bit confusing if you aren't aware of the subtleties of
dynamic versus static prefetching, but at least the "auto" string gives
slightly more of a hint that `true` is different from the default.

(In retrospect, we probably should have made `true` an alias for the
default, and chosen a separate value to opt into dynamic.)

Author: acdlite

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

@@ -133,7 +133,7 @@ type InternalLinkProps = {
    * Prefetching is only enabled in production.
    *
    * - In the **App Router**:
-   *   - `null` (default): Prefetch behavior depends on static vs dynamic routes:
+   *   - `"auto"`, `null`, `undefined` (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.
@@ -151,7 +151,7 @@ type InternalLinkProps = {
    * </Link>
    * ```
    */
-  prefetch?: boolean | null
+  prefetch?: boolean | 'auto' | null
 
   /**
    * (unstable) Switch to a dynamic prefetch on hover. Effectively the same as
@@ -366,7 +366,9 @@ export default function LinkComponent(
    * - 'unstable_dynamicOnHover': this starts in "auto" mode, but switches to "full" when the link is hovered
    */
   const appPrefetchKind =
-    prefetchProp === null ? PrefetchKind.AUTO : PrefetchKind.FULL
+    prefetchProp === null || prefetchProp === 'auto'
+      ? PrefetchKind.AUTO
+      : PrefetchKind.FULL
 
   if (process.env.NODE_ENV !== 'production') {
     function createPropError(args: {

packages/next/src/client/form-shared.tsx

@@ -19,7 +19,7 @@ type InternalFormProps = {
    * Prefetch can be disabled by passing `prefetch={false}`. Prefetching is only enabled in production.
    *
    * Options:
-   * - `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.
+   * - "auto", null, undefined (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.
    * - `false`: This will not prefetch any data.
    *
    * In pages dir, prefetching is not supported, and passing this prop will emit a warning.

packages/next/src/client/link.tsx

@@ -73,7 +73,7 @@ type InternalLinkProps = {
    * Prefetch can be disabled by passing `prefetch={false}`. Prefetching is only enabled in production.
    *
    * 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.
+   * - "auto", null, undefined (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.
    *
@@ -82,7 +82,7 @@ type InternalLinkProps = {
    * - `false`: Prefetching will not happen when entering the viewport, but will still happen on hover.
    * @defaultValue `true` (pages router) or `null` (app router)
    */
-  prefetch?: boolean | null
+  prefetch?: boolean | 'auto' | 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.

test/e2e/app-dir/segment-cache/prefetch-auto/app/dynamic/loading.tsx

@@ -0,0 +1,3 @@
+export default function Loading() {
+  return <div id="loading-boundary">Loading...</div>
+}

test/e2e/app-dir/segment-cache/prefetch-auto/app/dynamic/page.tsx

@@ -0,0 +1,6 @@
+import { connection } from 'next/server'
+
+export default async function Page() {
+  await connection()
+  return <div id="dynamic-content">Dynamic content</div>
+}

test/e2e/app-dir/segment-cache/prefetch-auto/app/layout.tsx

@@ -0,0 +1,11 @@
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}

test/e2e/app-dir/segment-cache/prefetch-auto/app/page.tsx

@@ -0,0 +1,20 @@
+import { LinkAccordion } from '../components/link-accordion'
+
+export default function Page() {
+  return (
+    <>
+      <p>
+        This page is used to test that prefetch="auto" uses the default
+        prefetching strategy (the same as if no prefetch prop is given).
+      </p>
+
+      <LinkAccordion
+        // @ts-expect-error: "auto" not yet part of public types
+        prefetch="auto"
+        href="/dynamic"
+      >
+        Dynamic page with loading boundary
+      </LinkAccordion>
+    </>
+  )
+}

test/e2e/app-dir/segment-cache/prefetch-auto/components/link-accordion.tsx

@@ -0,0 +1,23 @@
+'use client'
+
+import Link from 'next/link'
+import { useState } from 'react'
+
+export function LinkAccordion({ href, children }) {
+  const [isVisible, setIsVisible] = useState(false)
+  return (
+    <>
+      <input
+        type="checkbox"
+        checked={isVisible}
+        onChange={() => setIsVisible(!isVisible)}
+        data-link-accordion={href}
+      />
+      {isVisible ? (
+        <Link href={href}>{children}</Link>
+      ) : (
+        `${children} (link is hidden)`
+      )}
+    </>
+  )
+}

test/e2e/app-dir/segment-cache/prefetch-auto/next.config.js

@@ -0,0 +1,11 @@
+/**
+ * @type {import('next').NextConfig}
+ */
+const nextConfig = {
+  experimental: {
+    ppr: true,
+    dynamicIO: true,
+  },
+}
+
+module.exports = nextConfig

test/e2e/app-dir/segment-cache/prefetch-auto/prefetch-auto.test.ts

@@ -0,0 +1,59 @@
+import { nextTestSetup } from 'e2e-utils'
+import type * as Playwright from 'playwright'
+import { createRouterAct } from '../router-act'
+
+describe('<Link prefetch="auto">', () => {
+  const { next, isNextDev, skipped } = nextTestSetup({
+    files: __dirname,
+    skipDeployment: true,
+  })
+  if (isNextDev || skipped) {
+    it('disabled in development / deployment', () => {})
+    return
+  }
+
+  // NOTE: Since "auto" is just an alias for the default, I'm not bothering to
+  // write tests for every default prefetching behavior; that's covered by a
+  // bunch of other test suites. This is just a quick test to confirm that the
+  // alias exists.
+
+  it('<Link prefetch="auto"> works the same as if prefetch were undefined or null', async () => {
+    // Test that the link only prefetches the static part of the target page
+    let page: Playwright.Page
+    const browser = await next.browser('/', {
+      beforePageLoad(p: Playwright.Page) {
+        page = p
+      },
+    })
+    const act = createRouterAct(page)
+
+    // Reveal the link to trigger a prefetch
+    await act(async () => {
+      const linkToggle = await browser.elementByCss(
+        'input[data-link-accordion="/dynamic"]'
+      )
+      await linkToggle.click()
+    }, [
+      // Should prefetch the loading boundary
+      {
+        includes: 'Loading...',
+      },
+      // Should not prefetch the dynamic content
+      {
+        includes: 'Dynamic content',
+        block: 'reject',
+      },
+    ])
+
+    // Navigate to the page
+    await act(
+      async () => {
+        await browser.elementByCss('a[href="/dynamic"]').click()
+      },
+      {
+        // Now the dynamic content should be fetched
+        includes: 'Dynamic content',
+      }
+    )
+  })
+})