[Breaking] disable client router cache for page segments (#66039)

This configures the default client router cache `staleTime.dynamic`
value to be `0`.

This means that:
- Navigating between pages will always fire off a network request to get
RSC data for the page segment, rather than restoring from router cache
- Loading states will remain cached for 5 minutes (or whatever
`config.experimental.staleTimes.static` is set to)
- Shared layout data will continue to remain cached due to [partial
rendering](https://nextjs.org/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering)
- Back/forward behavior will still restore from cache to ensure the
browser can restore scroll position.

It's possible to opt-out of this, and into the previous behavior, by
setting the
[`staleTimes`](https://nextjs.org/docs/app/api-reference/next-config-js/staleTimes)
config in `next.config.js`:

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 30
    },
  },
}

module.exports = nextConfig
```

<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:

## For Contributors

### Improving Documentation

- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide

### Adding or Updating Examples

- The "examples guidelines" are followed from our contributing doc
https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
- Make sure the linting passes by running `pnpm build && pnpm lint`. See
https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md

### Fixing a bug

- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md

### Adding a feature

- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md


## For Maintainers

- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change

### What?

### Why?

### How?

Closes NEXT-
Fixes #

-->

docs/02-app/01-building-your-application/04-caching/index.mdx

@@ -364,7 +364,7 @@ The cache is stored in the browser's temporary memory. Two factors determine how
 
 - **Session**: The cache persists across navigation. However, it's cleared on page refresh.
 - **Automatic Invalidation Period**: The cache of an individual segment is automatically invalidated after a specific time. The duration depends on how the resource was [prefetched](/docs/app/api-reference/components/link#prefetch):
-  - **Default Prefetching** (`prefetch={null}` or unspecified): 30 seconds
+  - **Default Prefetching** (`prefetch={null}` or unspecified): 0 seconds
   - **Full Prefetching**: (`prefetch={true}` or `router.prefetch`): 5 minutes
 
 While a page refresh will clear **all** cached segments, the automatic invalidation period only affects the individual segment from the time it was prefetched.

docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx

@@ -28,7 +28,7 @@ module.exports = nextConfig
 The `static` and `dynamic` properties correspond with the time period (in seconds) based on different types of [link prefetching](/docs/app/api-reference/components/link#prefetch).
 
 - The `dynamic` property is used when the `prefetch` prop on `Link` is left unspecified or is set to `false`.
-  - Default: 30 seconds
+  - Default: 0 seconds (not cached)
 - The `static` property is used when the `prefetch` prop on `Link` is set to `true`, or when calling [`router.prefetch`](/docs/app/building-your-application/caching#routerprefetch).
   - Default: 5 minutes
 

packages/next/src/build/webpack/plugins/define-env-plugin.ts

@@ -178,7 +178,7 @@ export function getDefineEnv({
       config.experimental.manualClientBasePath ?? false,
     'process.env.__NEXT_CLIENT_ROUTER_DYNAMIC_STALETIME': JSON.stringify(
       isNaN(Number(config.experimental.staleTimes?.dynamic))
-        ? 30 // 30 seconds
+        ? 0
         : config.experimental.staleTimes?.dynamic
     ),
     'process.env.__NEXT_CLIENT_ROUTER_STATIC_STALETIME': JSON.stringify(

packages/next/src/client/components/router-reducer/prefetch-cache-utils.ts

@@ -239,7 +239,7 @@ export function prunePrefetchCache(
 }
 
 // These values are set by `define-env-plugin` (based on `nextConfig.experimental.staleTimes`)
-// and default to 5 minutes (static) / 30 seconds (dynamic)
+// and default to 5 minutes (static) / 0 seconds (dynamic)
 const DYNAMIC_STALETIME_MS =
   Number(process.env.__NEXT_CLIENT_ROUTER_DYNAMIC_STALETIME) * 1000
 

packages/next/src/server/config-shared.ts

@@ -964,7 +964,7 @@ export const defaultConfig: NextConfig = {
     optimizeServerReact: true,
     useEarlyImport: false,
     staleTimes: {
-      dynamic: 30,
+      dynamic: 0,
       static: 300,
     },
     allowDevelopmentBuild: undefined,

test/e2e/app-dir/app-client-cache/client-cache.defaults.test.ts

@@ -0,0 +1,352 @@
+import { nextTestSetup } from 'e2e-utils'
+import { check } from 'next-test-utils'
+import { BrowserInterface } from 'next-webdriver'
+import {
+  browserConfigWithFixedTime,
+  createRequestsListener,
+  fastForwardTo,
+  getPathname,
+} from './test-utils'
+
+describe('app dir client cache semantics (default semantics)', () => {
+  const { next, isNextDev } = nextTestSetup({
+    files: __dirname,
+  })
+
+  if (isNextDev) {
+    // dev doesn't support prefetch={true}, so this just performs a basic test to make sure data is reused for 30s
+    it('should return fresh data every navigation', async () => {
+      let browser = (await next.browser(
+        '/',
+        browserConfigWithFixedTime
+      )) as BrowserInterface
+
+      // navigate to prefetch-auto page
+      await browser.elementByCss('[href="/1"]').click()
+
+      let initialNumber = await browser.elementById('random-number').text()
+
+      // Navigate back to the index, and then back to the prefetch-auto page
+      await browser.elementByCss('[href="/"]').click()
+      await browser.eval(fastForwardTo, 5 * 1000)
+      await browser.elementByCss('[href="/1"]').click()
+
+      let newNumber = await browser.elementById('random-number').text()
+
+      expect(newNumber).not.toBe(initialNumber)
+    })
+  } else {
+    describe('prefetch={true}', () => {
+      let browser: BrowserInterface
+
+      beforeEach(async () => {
+        browser = (await next.browser(
+          '/',
+          browserConfigWithFixedTime
+        )) as BrowserInterface
+      })
+
+      it('should prefetch the full page', async () => {
+        const { getRequests, clearRequests } =
+          await createRequestsListener(browser)
+        await check(() => {
+          return getRequests().some(
+            ([url, didPartialPrefetch]) =>
+              getPathname(url) === '/0' && !didPartialPrefetch
+          )
+            ? 'success'
+            : 'fail'
+        }, 'success')
+
+        clearRequests()
+
+        await browser
+          .elementByCss('[href="/0?timeout=0"]')
+          .click()
+          .waitForElementByCss('#random-number')
+
+        expect(
+          getRequests().every(([url]) => getPathname(url) !== '/0')
+        ).toEqual(true)
+      })
+      it('should re-use the cache for the full page, only for 5 mins', async () => {
+        const randomNumber = await browser
+          .elementByCss('[href="/0?timeout=0"]')
+          .click()
+          .waitForElementByCss('#random-number')
+          .text()
+
+        await browser.elementByCss('[href="/"]').click()
+
+        const number = await browser
+          .elementByCss('[href="/0?timeout=0"]')
+          .click()
+          .waitForElementByCss('#random-number')
+          .text()
+
+        expect(number).toBe(randomNumber)
+
+        await browser.eval(fastForwardTo, 5 * 60 * 1000)
+
+        await browser.elementByCss('[href="/"]').click()
+
+        const newNumber = await browser
+          .elementByCss('[href="/0?timeout=0"]')
+          .click()
+          .waitForElementByCss('#random-number')
+          .text()
+
+        expect(newNumber).not.toBe(randomNumber)
+      })
+
+      it('should prefetch again after 5 mins if the link is visible again', async () => {
+        const { getRequests, clearRequests } =
+          await createRequestsListener(browser)
+
+        await check(() => {
+          return getRequests().some(
+            ([url, didPartialPrefetch]) =>
+              getPathname(url) === '/0' && !didPartialPrefetch
+          )
+            ? 'success'
+            : 'fail'
+        }, 'success')
+
+        const randomNumber = await browser
+          .elementByCss('[href="/0?timeout=0"]')
+          .click()
+          .waitForElementByCss('#random-number')
+          .text()
+
+        await browser.eval(fastForwardTo, 5 * 60 * 1000)
+        clearRequests()
+
+        await browser.elementByCss('[href="/"]').click()
+
+        await check(() => {
+          return getRequests().some(
+            ([url, didPartialPrefetch]) =>
+              getPathname(url) === '/0' && !didPartialPrefetch
+          )
+            ? 'success'
+            : 'fail'
+        }, 'success')
+
+        const number = await browser
+          .elementByCss('[href="/0?timeout=0"]')
+          .click()
+          .waitForElementByCss('#random-number')
+          .text()
+
+        expect(number).not.toBe(randomNumber)
+      })
+    })
+    describe('prefetch={false}', () => {
+      let browser: BrowserInterface
+
+      beforeEach(async () => {
+        browser = (await next.browser(
+          '/',
+          browserConfigWithFixedTime
+        )) as BrowserInterface
+      })
+      it('should not prefetch the page at all', async () => {
+        const { getRequests } = await createRequestsListener(browser)
+
+        await browser
+          .elementByCss('[href="/2"]')
+          .click()
+          .waitForElementByCss('#random-number')
+
+        expect(
+          getRequests().filter(([url]) => getPathname(url) === '/2')
+        ).toHaveLength(1)
+
+        expect(
+          getRequests().some(
+            ([url, didPartialPrefetch]) =>
+              getPathname(url) === '/2' && didPartialPrefetch
+          )
+        ).toBe(false)
+      })
+      it('should not re-use the page segment cache', async () => {
+        const randomNumber = await browser
+          .elementByCss('[href="/2"]')
+          .click()
+          .waitForElementByCss('#random-number')
+          .text()
+
+        await browser.elementByCss('[href="/"]').click()
+
+        const number = await browser
+          .elementByCss('[href="/2"]')
+          .click()
+          .waitForElementByCss('#random-number')
+          .text()
+
+        expect(number).not.toBe(randomNumber)
+
+        await browser.eval(fastForwardTo, 30 * 1000)
+
+        await browser.elementByCss('[href="/"]').click()
+
+        const newNumber = await browser
+          .elementByCss('[href="/2"]')
+          .click()
+          .waitForElementByCss('#random-number')
+          .text()
+
+        expect(newNumber).not.toBe(randomNumber)
+      })
+    })
+    describe('prefetch={undefined} - default', () => {
+      let browser: BrowserInterface
+
+      beforeEach(async () => {
+        browser = (await next.browser(
+          '/',
+          browserConfigWithFixedTime
+        )) as BrowserInterface
+      })
+
+      it('should prefetch partially a dynamic page', async () => {
+        const { getRequests, clearRequests } =
+          await createRequestsListener(browser)
+
+        await check(() => {
+          return getRequests().some(
+            ([url, didPartialPrefetch]) =>
+              getPathname(url) === '/1' && didPartialPrefetch
+          )
+            ? 'success'
+            : 'fail'
+        }, 'success')
+
+        clearRequests()
+
+        await browser
+          .elementByCss('[href="/1"]')
+          .click()
+          .waitForElementByCss('#random-number')
+
+        expect(
+          getRequests().some(
+            ([url, didPartialPrefetch]) =>
+              getPathname(url) === '/1' && !didPartialPrefetch
+          )
+        ).toBe(true)
+      })
+      it('should not re-use the page segment cache', async () => {
+        const randomNumber = await browser
+          .elementByCss('[href="/1"]')
+          .click()
+          .waitForElementByCss('#random-number')
+          .text()
+
+        await browser.elementByCss('[href="/"]').click()
+
+        const number = await browser
+          .elementByCss('[href="/1"]')
+          .click()
+          .waitForElementByCss('#random-number')
+          .text()
+
+        expect(number).not.toBe(randomNumber)
+
+        await browser.eval(fastForwardTo, 5 * 1000)
+
+        await browser.elementByCss('[href="/"]').click()
+
+        const newNumber = await browser
+          .elementByCss('[href="/1"]')
+          .click()
+          .waitForElementByCss('#random-number')
+          .text()
+
+        expect(newNumber).not.toBe(randomNumber)
+
+        await browser.eval(fastForwardTo, 30 * 1000)
+
+        await browser.elementByCss('[href="/"]').click()
+
+        const newNumber2 = await browser
+          .elementByCss('[href="/1"]')
+          .click()
+          .waitForElementByCss('#random-number')
+          .text()
+
+        expect(newNumber2).not.toBe(newNumber)
+      })
+
+      it('should refetch the full page after 5 mins', async () => {
+        const randomLoadingNumber = await browser
+          .elementByCss('[href="/1?timeout=1000"]')
+          .click()
+          .waitForElementByCss('#loading')
+          .text()
+
+        const randomNumber = await browser
+          .waitForElementByCss('#random-number')
+          .text()
+
+        await browser.eval(fastForwardTo, 5 * 60 * 1000)
+
+        await browser
+          .elementByCss('[href="/"]')
+          .click()
+          .waitForElementByCss('[href="/1?timeout=1000"]')
+
+        const newLoadingNumber = await browser
+          .elementByCss('[href="/1?timeout=1000"]')
+          .click()
+          .waitForElementByCss('#loading')
+          .text()
+
+        const newNumber = await browser
+          .waitForElementByCss('#random-number')
+          .text()
+
+        expect(newLoadingNumber).not.toBe(randomLoadingNumber)
+
+        expect(newNumber).not.toBe(randomNumber)
+      })
+
+      it('should respect a loading boundary that returns `null`', async () => {
+        await browser.elementByCss('[href="/null-loading"]').click()
+
+        // the page content should disappear immediately
+        expect(
+          await browser.hasElementByCssSelector('[href="/null-loading"]')
+        ).toBeFalse()
+
+        // the root layout should still be visible
+        expect(await browser.hasElementByCssSelector('#root-layout')).toBeTrue()
+
+        // the dynamic content should eventually appear
+        await browser.waitForElementByCss('#random-number')
+        expect(
+          await browser.hasElementByCssSelector('#random-number')
+        ).toBeTrue()
+      })
+    })
+
+    it('should renew the initial seeded data after expiration time', async () => {
+      const browser = (await next.browser(
+        '/without-loading/1',
+        browserConfigWithFixedTime
+      )) as BrowserInterface
+
+      const initialNumber = await browser.elementById('random-number').text()
+
+      // Expire the cache
+      await browser.eval(fastForwardTo, 30 * 1000)
+      await browser.elementByCss('[href="/without-loading"]').click()
+      await browser.elementByCss('[href="/without-loading/1"]').click()
+
+      const newNumber = await browser.elementById('random-number').text()
+
+      // The number should be different, as the seeded data has expired after 30s
+      expect(newNumber).not.toBe(initialNumber)
+    })
+  }
+})