Unverified Commit 86cbc1f5 authored by Zack Tanner's avatar Zack Tanner Committed by GitHub

add experimental client router cache config (#62856)

This introduces an experimental router flag (`experimental.staleTimes`)
to change the router cache behavior. Specifically:

```ts
// next.config.js
module.exports = {
  experimental: {
    staleTimes: {
      dynamic: <seconds>,
      static: <seconds>,
    },
  },
};
```

- `dynamic` is the value that is used when the `prefetch` `Link` prop is
left unspecified. (Default 30 seconds)
- `static` is the value that is used when the `prefetch` `Link` prop is
`true`. (Default 5 minutes)

Additional details:
- Loading boundaries are considered reusable for the time period
indicated by the `static` property (default 5 minutes)
- This doesn't disable partial rendering support, **meaning shared
layouts won't automatically be refetched every navigation, only the new
segment data**.
- This also doesn't change back/forward caching behavior to ensure
things like scroll restoration etc still work nicely.

Please see the original proposal
[here](https://github.com/vercel/next.js/discussions/54075#discussioncomment-6754339)
for more information. The primary difference is that this is a global
configuration, rather than a per-segment configuration, and it isn't
applied to layouts. (We expect this to be a "stop-gap" and not the final
router caching solution)

Closes NEXT-2703
parent 944159a6
......@@ -171,6 +171,16 @@ export function getDefineEnv({
'process.env.__NEXT_MIDDLEWARE_MATCHERS': middlewareMatchers ?? [],
'process.env.__NEXT_MANUAL_CLIENT_BASE_PATH':
config.experimental.manualClientBasePath ?? false,
'process.env.__NEXT_CLIENT_ROUTER_DYNAMIC_STALETIME': JSON.stringify(
isNaN(Number(config.experimental.staleTimes?.dynamic))
? 30 // 30 seconds
: config.experimental.staleTimes?.dynamic
),
'process.env.__NEXT_CLIENT_ROUTER_STATIC_STALETIME': JSON.stringify(
isNaN(Number(config.experimental.staleTimes?.static))
? 5 * 60 // 5 minutes
: config.experimental.staleTimes?.static
),
'process.env.__NEXT_CLIENT_ROUTER_FILTER_ENABLED':
config.experimental.clientRouterFilter ?? true,
'process.env.__NEXT_CLIENT_ROUTER_S_FILTER':
......
......@@ -243,31 +243,38 @@ export function prunePrefetchCache(
}
}
const FIVE_MINUTES = 5 * 60 * 1000
const THIRTY_SECONDS = 30 * 1000
// These values are set by `define-env-plugin` (based on `nextConfig.experimental.staleTimes`)
// and default to 5 minutes (static) / 30 seconds (dynamic)
const DYNAMIC_STALETIME_MS =
Number(process.env.__NEXT_CLIENT_ROUTER_DYNAMIC_STALETIME) * 1000
const STATIC_STALETIME_MS =
Number(process.env.__NEXT_CLIENT_ROUTER_STATIC_STALETIME) * 1000
function getPrefetchEntryCacheStatus({
kind,
prefetchTime,
lastUsedTime,
}: PrefetchCacheEntry): PrefetchCacheEntryStatus {
// if the cache entry was prefetched or read less than 30s ago, then we want to re-use it
if (Date.now() < (lastUsedTime ?? prefetchTime) + THIRTY_SECONDS) {
// We will re-use the cache entry data for up to the `dynamic` staletime window.
if (Date.now() < (lastUsedTime ?? prefetchTime) + DYNAMIC_STALETIME_MS) {
return lastUsedTime
? PrefetchCacheEntryStatus.reusable
: PrefetchCacheEntryStatus.fresh
}
// if the cache entry was prefetched less than 5 mins ago, then we want to re-use only the loading state
// For "auto" prefetching, we'll re-use only the loading boundary for up to `static` staletime window.
// A stale entry will only re-use the `loading` boundary, not the full data.
// This will trigger a "lazy fetch" for the full data.
if (kind === 'auto') {
if (Date.now() < prefetchTime + FIVE_MINUTES) {
if (Date.now() < prefetchTime + STATIC_STALETIME_MS) {
return PrefetchCacheEntryStatus.stale
}
}
// if the cache entry was prefetched less than 5 mins ago and was a "full" prefetch, then we want to re-use it "full
// for "full" prefetching, we'll re-use the cache entry data for up to `static` staletime window.
if (kind === 'full') {
if (Date.now() < prefetchTime + FIVE_MINUTES) {
if (Date.now() < prefetchTime + STATIC_STALETIME_MS) {
return PrefetchCacheEntryStatus.reusable
}
}
......
......@@ -247,6 +247,12 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
validator: z.string().optional(),
})
.optional(),
staleTimes: z
.object({
dynamic: z.number().optional(),
static: z.number().optional(),
})
.optional(),
clientRouterFilter: z.boolean().optional(),
clientRouterFilterRedirects: z.boolean().optional(),
clientRouterFilterAllowedRate: z.number().optional(),
......
......@@ -187,6 +187,16 @@ export interface ExperimentalConfig {
strictNextHead?: boolean
clientRouterFilter?: boolean
clientRouterFilterRedirects?: boolean
/**
* This config can be used to override the cache behavior for the client router.
* These values indicate the time, in seconds, that the cache should be considered
* reusable. When the `prefetch` Link prop is left unspecified, this will use the `dynamic` value.
* When the `prefetch` Link prop is set to `true`, this will use the `static` value.
*/
staleTimes?: {
dynamic?: number
static?: number
}
// decimal for percent for possible false positives
// e.g. 0.01 for 10% potential false matches lower
// percent increases size of the filter
......@@ -926,6 +936,10 @@ export const defaultConfig: NextConfig = {
missingSuspenseWithCSRBailout: true,
optimizeServerReact: true,
useEarlyImport: false,
staleTimes: {
dynamic: 30,
static: 300,
},
},
}
......
......@@ -7,6 +7,11 @@ export default function HomePage() {
To Random Number - prefetch: true
</Link>
</div>
<div>
<Link href="/0?timeout=1000" prefetch={true}>
To Random Number - prefetch: true, slow
</Link>
</div>
<div>
<Link href="/1">To Random Number - prefetch: auto</Link>
</div>
......@@ -15,6 +20,11 @@ export default function HomePage() {
To Random Number 2 - prefetch: false
</Link>
</div>
<div>
<Link href="/2?timeout=1000" prefetch={false}>
To Random Number 2 - prefetch: false, slow
</Link>
</div>
<div>
<Link href="/1?timeout=1000">
To Random Number - prefetch: auto, slow
......
import Link from 'next/link'
export default async function Page({ searchParams: { timeout } }) {
const randomNumber = await new Promise((resolve) => {
setTimeout(
() => {
resolve(Math.random())
},
timeout !== undefined ? Number.parseInt(timeout, 10) : 0
)
})
return (
<>
<div>
<Link href="/without-loading">Back to Home</Link>
</div>
<div id="random-number">{randomNumber}</div>
</>
)
}
import Link from 'next/link'
export default function Page() {
return (
<>
<div>
<Link href="/without-loading/0?timeout=0" prefetch={true}>
To Random Number - prefetch: true
</Link>
</div>
<div>
<Link href="/without-loading/0?timeout=1000" prefetch={true}>
To Random Number - prefetch: true, slow
</Link>
</div>
<div>
<Link href="/without-loading/1">To Random Number - prefetch: auto</Link>
</div>
<div>
<Link href="/without-loading/2" prefetch={false}>
To Random Number 2 - prefetch: false
</Link>
</div>
<div>
<Link href="/without-loading/2?timeout=1000" prefetch={false}>
To Random Number 2 - prefetch: false, slow
</Link>
</div>
<div>
<Link href="/without-loading/1?timeout=1000">
To Random Number - prefetch: auto, slow
</Link>
</div>
</>
)
}
import { nextTestSetup } from 'e2e-utils'
import { browserConfigWithFixedTime, fastForwardTo } from './test-utils'
describe('app dir client cache semantics (experimental staleTimes)', () => {
describe('dynamic: 0', () => {
const { next, isNextDev } = nextTestSetup({
files: __dirname,
nextConfig: {
experimental: { staleTimes: { dynamic: 0 } },
},
})
if (isNextDev) {
// since the router behavior is different in development mode (no viewport prefetching + liberal revalidation)
// we only check the production behavior
it('should skip dev', () => {})
return
}
describe('prefetch={true}', () => {
it('should re-use the cache for 5 minutes (default "static" time)', async () => {
const browser = await next.browser('/', browserConfigWithFixedTime)
let initialRandomNumber = await browser
.elementByCss('[href="/0?timeout=0"]')
.click()
.waitForElementByCss('#random-number')
.text()
await browser.elementByCss('[href="/"]').click()
let newRandomNumber = await browser
.elementByCss('[href="/0?timeout=0"]')
.click()
.waitForElementByCss('#random-number')
.text()
expect(initialRandomNumber).toBe(newRandomNumber)
await browser.eval(fastForwardTo, 30 * 1000) // fast forward 30 seconds
await browser.elementByCss('[href="/"]').click()
newRandomNumber = await browser
.elementByCss('[href="/0?timeout=0"]')
.click()
.waitForElementByCss('#random-number')
.text()
expect(initialRandomNumber).toBe(newRandomNumber)
await browser.eval(fastForwardTo, 5 * 60 * 1000) // fast forward 5 minutes
await browser.elementByCss('[href="/"]').click()
newRandomNumber = await browser
.elementByCss('[href="/0?timeout=0"]')
.click()
.waitForElementByCss('#random-number')
.text()
expect(initialRandomNumber).not.toBe(newRandomNumber)
})
})
describe('prefetch={false}', () => {
it('should trigger a loading state before fetching the page, followed by fresh data on every subsequent navigation', async () => {
const browser = await next.browser('/', browserConfigWithFixedTime)
// this test introduces an artificial delay in rendering the requested page, so we verify a loading state is rendered
await browser
.elementByCss('[href="/2?timeout=1000"]')
.click()
.waitForElementByCss('#loading')
const initialRandomNumber = await browser
.waitForElementByCss('#random-number')
.text()
await browser.elementByCss('[href="/"]').click()
await browser.eval(fastForwardTo, 5 * 1000) // fast forward 5 seconds
const newRandomNumber = await browser
.elementByCss('[href="/2?timeout=1000"]')
.click()
.waitForElementByCss('#random-number')
.text()
expect(initialRandomNumber).not.toBe(newRandomNumber)
})
describe('without a loading boundary', () => {
it('should get fresh data on every subsequent navigation', async () => {
const browser = await next.browser('/', browserConfigWithFixedTime)
const initialRandomNumber = await browser
.elementByCss('[href="/2?timeout=1000"]')
.click()
.waitForElementByCss('#random-number')
.text()
await browser.elementByCss('[href="/"]').click()
await browser.eval(fastForwardTo, 5 * 1000) // fast forward 5 seconds
const newRandomNumber = await browser
.elementByCss('[href="/2?timeout=1000"]')
.click()
.waitForElementByCss('#random-number')
.text()
expect(initialRandomNumber).not.toBe(newRandomNumber)
})
})
})
describe('prefetch={undefined} - default', () => {
it('should trigger a loading state before fetching the page, followed by fresh data on every subsequent navigation', async () => {
const browser = await next.browser('/', browserConfigWithFixedTime)
// this test introduces an artificial delay in rendering the requested page, so we verify a loading state is rendered
await browser
.elementByCss('[href="/1?timeout=1000"]')
.click()
.waitForElementByCss('#loading')
const initialRandomNumber = await browser
.waitForElementByCss('#random-number')
.text()
await browser.elementByCss('[href="/"]').click()
await browser.eval(fastForwardTo, 5 * 1000) // fast forward 5 seconds
const newRandomNumber = await browser
.elementByCss('[href="/1?timeout=1000"]')
.click()
.waitForElementByCss('#random-number')
.text()
expect(initialRandomNumber).not.toBe(newRandomNumber)
})
describe('without a loading boundary', () => {
it('should get fresh data on every subsequent navigation', async () => {
const browser = await next.browser(
'/without-loading',
browserConfigWithFixedTime
)
const initialRandomNumber = await browser
.elementByCss('[href="/without-loading/1?timeout=1000"]')
.click()
.waitForElementByCss('#random-number')
.text()
await browser.elementByCss('[href="/without-loading"]').click()
const newRandomNumber = await browser
.elementByCss('[href="/without-loading/1?timeout=1000"]')
.click()
.waitForElementByCss('#random-number')
.text()
expect(initialRandomNumber).not.toBe(newRandomNumber)
})
})
})
})
describe('static: 180', () => {
const { next, isNextDev } = nextTestSetup({
files: __dirname,
nextConfig: {
experimental: { staleTimes: { static: 180 } },
},
})
if (isNextDev) {
// since the router behavior is different in development mode (no viewport prefetching + liberal revalidation)
// we only check the production behavior
it('should skip dev', () => {})
return
}
describe('prefetch={true}', () => {
it('should use the custom static override time (3 minutes)', async () => {
const browser = await next.browser('/', browserConfigWithFixedTime)
let initialRandomNumber = await browser
.elementByCss('[href="/0?timeout=0"]')
.click()
.waitForElementByCss('#random-number')
.text()
await browser.elementByCss('[href="/"]').click()
let newRandomNumber = await browser
.elementByCss('[href="/0?timeout=0"]')
.click()
.waitForElementByCss('#random-number')
.text()
expect(initialRandomNumber).toBe(newRandomNumber)
await browser.eval(fastForwardTo, 30 * 1000) // fast forward 30 seconds
await browser.elementByCss('[href="/"]').click()
newRandomNumber = await browser
.elementByCss('[href="/0?timeout=0"]')
.click()
.waitForElementByCss('#random-number')
.text()
expect(initialRandomNumber).toBe(newRandomNumber)
await browser.eval(fastForwardTo, 3 * 60 * 1000) // fast forward 3 minutes
await browser.elementByCss('[href="/"]').click()
newRandomNumber = await browser
.elementByCss('[href="/0?timeout=0"]')
.click()
.waitForElementByCss('#random-number')
.text()
expect(initialRandomNumber).not.toBe(newRandomNumber)
})
})
describe('prefetch={undefined} - default', () => {
it('should re-use the loading boundary for the custom static override time (3 minutes)', async () => {
const browser = await next.browser('/', browserConfigWithFixedTime)
const loadingRandomNumber = await browser
.elementByCss('[href="/1?timeout=1000"]')
.click()
.waitForElementByCss('#loading')
.text()
await browser.elementByCss('[href="/"]').click()
await browser.eval(fastForwardTo, 2 * 60 * 1000) // fast forward 2 minutes
let newLoadingNumber = await browser
.elementByCss('[href="/1?timeout=1000"]')
.click()
.waitForElementByCss('#loading')
.text()
expect(loadingRandomNumber).toBe(newLoadingNumber)
await browser.elementByCss('[href="/"]').click()
await browser.eval(fastForwardTo, 2 * 60 * 1000) // fast forward 2 minutes
newLoadingNumber = await browser
.elementByCss('[href="/1?timeout=1000"]')
.click()
.waitForElementByCss('#loading')
.text()
expect(loadingRandomNumber).not.toBe(newLoadingNumber)
})
})
})
})
import { createNextDescribe } from 'e2e-utils'
import { check } from 'next-test-utils'
import { BrowserInterface } from 'test/lib/browsers/base'
import type { Request } from 'playwright'
const getPathname = (url: string) => {
const urlObj = new URL(url)
return urlObj.pathname
}
const browserConfigWithFixedTime = {
beforePageLoad: (page) => {
page.addInitScript(() => {
const startTime = new Date()
const fixedTime = new Date('2023-04-17T00:00:00Z')
// Override the Date constructor
// @ts-ignore
// eslint-disable-next-line no-native-reassign
Date = class extends Date {
constructor() {
super()
// @ts-ignore
return new startTime.constructor(fixedTime)
}
static now() {
return fixedTime.getTime()
}
}
})
},
}
const fastForwardTo = (ms) => {
// Increment the fixed time by the specified duration
const currentTime = new Date()
currentTime.setTime(currentTime.getTime() + ms)
// Update the Date constructor to use the new fixed time
// @ts-ignore
// eslint-disable-next-line no-native-reassign
Date = class extends Date {
constructor() {
super()
// @ts-ignore
return new currentTime.constructor(currentTime)
}
static now() {
return currentTime.getTime()
}
}
}
const createRequestsListener = async (browser: BrowserInterface) => {
// wait for network idle
await browser.waitForIdleNetwork()
let requests = []
browser.on('request', (req: Request) => {
requests.push([req.url(), !!req.headers()['next-router-prefetch']])
})
await browser.refresh()
return {
getRequests: () => requests,
clearRequests: () => {
requests = []
},
}
}
import {
browserConfigWithFixedTime,
createRequestsListener,
fastForwardTo,
getPathname,
} from './test-utils'
createNextDescribe(
'app dir client cache semantics',
......@@ -455,7 +390,6 @@ createNextDescribe(
).toBeTrue()
})
})
it('should seed the prefetch cache with the fetched page data', async () => {
const browser = (await next.browser(
'/1',
......@@ -474,10 +408,6 @@ createNextDescribe(
// The number should be the same as we've seeded it in the prefetch cache when we loaded the full page
expect(newNumber).toBe(initialNumber)
})
describe('router.push', () => {
it('should re-use the cache for 30 seconds', async () => {})
it('should fully refetch the page after 30 seconds', async () => {})
})
}
}
)
import { BrowserInterface } from 'test/lib/browsers/base'
import type { Request } from 'playwright'
export const getPathname = (url: string) => {
const urlObj = new URL(url)
return urlObj.pathname
}
export const browserConfigWithFixedTime = {
beforePageLoad: (page) => {
page.addInitScript(() => {
const startTime = new Date()
const fixedTime = new Date('2023-04-17T00:00:00Z')
// Override the Date constructor
// @ts-ignore
// eslint-disable-next-line no-native-reassign
Date = class extends Date {
constructor() {
super()
// @ts-ignore
return new startTime.constructor(fixedTime)
}
static now() {
return fixedTime.getTime()
}
}
})
},
}
export const fastForwardTo = (ms) => {
// Increment the fixed time by the specified duration
const currentTime = new Date()
currentTime.setTime(currentTime.getTime() + ms)
// Update the Date constructor to use the new fixed time
// @ts-ignore
// eslint-disable-next-line no-native-reassign
Date = class extends Date {
constructor() {
super()
// @ts-ignore
return new currentTime.constructor(currentTime)
}
static now() {
return currentTime.getTime()
}
}
}
export const createRequestsListener = async (browser: BrowserInterface) => {
// wait for network idle
await browser.waitForIdleNetwork()
let requests = []
browser.on('request', (req: Request) => {
requests.push([req.url(), !!req.headers()['next-router-prefetch']])
})
await browser.refresh()
return {
getRequests: () => requests,
clearRequests: () => {
requests = []
},
}
}
......@@ -75,7 +75,8 @@
"test/e2e/app-dir/ppr/**/*",
"test/e2e/app-dir/ppr-*/**/*",
"test/e2e/app-dir/app-prefetch*/**/*",
"test/e2e/app-dir/searchparams-static-bailout/searchparams-static-bailout.test.ts"
"test/e2e/app-dir/searchparams-static-bailout/searchparams-static-bailout.test.ts",
"test/e2e/app-dir/app-client-cache/client-cache.experimental.test.ts"
]
}
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment