Unverified Commit 83e99f0a authored by Josh Story's avatar Josh Story Committed by GitHub

Exclude stale under 5 minutes from app shells (#95833)

App Shells are meant to be useful for handling navigations that are not
prefetched. If the stale time is very low then they must be evicted
often from the client router and thus their utility is undermined. We
now exclude caches that have a stale time under 5 minutes from app
shells.

For the default cacheLife profiles this means only the `seconds` profile
is excluded becasue every other profile has a stale of exactly 5 minutes
at this time.

In the future we may want to allow for this threshhold to be configured.
This shouldn't be too disruptive since generally content that is
changing often is likely not in your app shell to begin with.
parent 22fa026c
...@@ -1419,5 +1419,6 @@ ...@@ -1419,5 +1419,6 @@
"1418": "TypeScript %s does not provide the compiler API required by Next.js. Enable %s in your Next.js config to use the TypeScript CLI, or install TypeScript 6 instead.", "1418": "TypeScript %s does not provide the compiler API required by Next.js. Enable %s in your Next.js config to use the TypeScript CLI, or install TypeScript 6 instead.",
"1419": "TypeScript CLI interrupted by %s", "1419": "TypeScript CLI interrupted by %s",
"1420": "shouldTrackSyncInterrupt allowed a sync IO interrupt in an unexpected stage: %s", "1420": "shouldTrackSyncInterrupt allowed a sync IO interrupt in an unexpected stage: %s",
"1421": "The lazy module is still loading. It must be awaited with `waitUntilLoaded()` before it can be accessed." "1421": "The lazy module is still loading. It must be awaited with `waitUntilLoaded()` before it can be accessed.",
"1422": "MIN_PREFETCHABLE_STALE must not exceed MIN_SHELL_STALE."
} }
import { InvariantError } from '../../shared/lib/invariant-error'
export const MIN_PRERENDERABLE_EXPIRE = 300 // 5 minutes export const MIN_PRERENDERABLE_EXPIRE = 300 // 5 minutes
export const MIN_PREFETCHABLE_STALE = 30 // 30 seconds export const MIN_PREFETCHABLE_STALE = 30 // 30 seconds
export const MIN_SHELL_STALE = 300 // 5 minutes
if (process.env.NODE_ENV !== 'production') {
if (MIN_PREFETCHABLE_STALE > MIN_SHELL_STALE) {
throw new InvariantError(
'MIN_PREFETCHABLE_STALE must not exceed MIN_SHELL_STALE.'
)
}
}
...@@ -54,6 +54,45 @@ export default function Page() { ...@@ -54,6 +54,45 @@ export default function Page() {
</li> </li>
</ul> </ul>
<h2>Short-stale posts (allow-runtime)</h2>
<p>
These posts render cached content with a stale time below the App Shell
threshold (5 minutes). The short-lived content is excluded from the App
Shell so the shell can be reused on the client for longer than the
content&apos;s stale time.
</p>
<ul>
<li>
<LinkAccordion href="/short-stale/1">
Short-stale post 1
</LinkAccordion>
</li>
<li>
<Link href="/short-stale/124" prefetch={false}>
Unprefetched short-stale post
</Link>
</li>
</ul>
<h2>Static short-stale posts</h2>
<p>
Fully prerendered posts that render cached content with a stale time
below the App Shell threshold. The short-lived content is part of the
static prerender, but excluded from the extracted App Shell.
</p>
<ul>
<li>
<LinkAccordion href="/static-short-stale/1">
Static short-stale post 1
</LinkAccordion>
</li>
<li>
<Link href="/static-short-stale/124" prefetch={false}>
Unprefetched static short-stale post
</Link>
</li>
</ul>
<h2>Partial posts</h2> <h2>Partial posts</h2>
<ul> <ul>
<li> <li>
......
import { Suspense } from 'react'
import { cacheLife } from 'next/cache'
import { connection } from 'next/server'
type Params = { id: string }
export const prefetch = 'allow-runtime'
// This page mixes cached content with different stale times. Cached content
// with a stale time of at least 5 minutes is part of the App Shell. Cached
// content with a shorter stale time is excluded from the App Shell — it
// resolves in the post-shell stage — so the shell can be reused on the client
// for longer than the content's stale time.
export default function Page({ params }: { params: Promise<Params> }) {
return (
<main>
{/* stale: 5 minutes (the App Shell threshold) — included in the
App Shell. */}
<Suspense
fallback={<p id="long-stale-loading">Loading long-lived content...</p>}
>
<LongStaleCached />
</Suspense>
{/* stale: 60 seconds (below the App Shell threshold) — excluded from
the App Shell. */}
<Suspense
fallback={
<p id="short-stale-loading">Loading short-lived content...</p>
}
>
<ShortStaleCached />
</Suspense>
{/* The fallback is the App Shell — the part of the page that
doesn't depend on params. */}
<Suspense fallback={<p id="shell">App shell for short-stale</p>}>
<ParamsDependent params={params} />
</Suspense>
</main>
)
}
async function LongStaleCached() {
'use cache'
cacheLife('hours') // stale: 5 minutes
return <p id="long-stale-content">Long-lived cached content</p>
}
async function ShortStaleCached() {
'use cache'
cacheLife({ stale: 60 }) // revalidate and expire use the default profile
return <p id="short-stale-content">Short-lived cached content</p>
}
async function ParamsDependent({ params }: { params: Promise<Params> }) {
const { id } = await params
return (
<>
<p id="param-value">{`Post ${id}`}</p>
<Suspense
fallback={<p id="dynamic-loading">Loading dynamic content...</p>}
>
<Dynamic id={id} />
</Suspense>
</>
)
}
async function Dynamic({ id }: { id: string }) {
await connection()
return <p id="dynamic-content">{`Post body for ${id}`}</p>
}
import { Suspense } from 'react'
import { cacheLife } from 'next/cache'
type Params = { id: string }
// This page is fully static: all params are statically known via
// `generateStaticParams`, so the page is prerendered for every URL at build
// time. It mixes cached content with different stale times. Cached content
// with a stale time of at least 5 minutes is part of the App Shell. Cached
// content with a shorter stale time resolves in the post-shell stage: it's
// still part of the static prerender, but excluded from the App Shell prefix
// that the client extracts (using the shell byte offset in the response) and
// reuses across URLs.
export async function generateStaticParams() {
return [{ id: '1' }, { id: '2' }, { id: '124' }]
}
export default function Page({ params }: { params: Promise<Params> }) {
return (
<main>
{/* stale: 5 minutes (the App Shell threshold) — included in the
App Shell. */}
<Suspense
fallback={
<p id="static-long-stale-loading">Loading long-lived content...</p>
}
>
<LongStaleCached />
</Suspense>
{/* stale: 60 seconds (below the App Shell threshold) — excluded from
the App Shell. */}
<Suspense
fallback={
<p id="static-short-stale-loading">Loading short-lived content...</p>
}
>
<ShortStaleCached />
</Suspense>
<Suspense
fallback={
<p id="static-shell">App shell for static short-stale posts</p>
}
>
<ParamsDependent params={params} />
</Suspense>
</main>
)
}
async function LongStaleCached() {
'use cache'
cacheLife('hours') // stale: 5 minutes
return <p id="static-long-stale-content">Long-lived cached content</p>
}
async function ShortStaleCached() {
'use cache'
cacheLife({ stale: 60 }) // revalidate and expire use the default profile
return <p id="static-short-stale-content">Short-lived cached content</p>
}
async function ParamsDependent({ params }: { params: Promise<Params> }) {
const { id } = await params
return <p id="static-content">{`Static post ${id}`}</p>
}
...@@ -290,6 +290,127 @@ describe('App Shell prefetching', () => { ...@@ -290,6 +290,127 @@ describe('App Shell prefetching', () => {
) )
}) })
it('excludes cached content with a short stale time from a runtime App Shell', async () => {
let page: Playwright.Page
const browser = await next.browser('/', {
beforePageLoad(p: Playwright.Page) {
page = p
},
})
const act = createRouterAct(page, { includeAppShellRequests: true })
// Reveal the LinkAccordion for /short-stale/1. This caches the App Shell
// for the route. The page renders two cached components: one with a stale
// time of 5 minutes (the App Shell threshold), which is included in the
// shell, and one with a stale time of 60 seconds, which is excluded from
// the shell so the shell can be reused on the client for longer than the
// content's stale time.
await act(
async () => {
await browser
.elementByCss('input[data-link-accordion="/short-stale/1"]')
.click()
},
{ includes: 'App shell for short-stale' }
)
await act(async () => {
// Click the link to /short-stale/124. This link is rendered with
// prefetch={false}, so it was never prefetched. The cached App Shell
// should render immediately, before any navigation response arrives.
await browser.elementByCss('a[href="/short-stale/124"]').click()
// While the navigation response is blocked (we're still in the `act`
// block), the cached App Shell should already be visible, including
// the long-lived cached content.
expect(await browser.elementById('shell').text()).toEqual(
'App shell for short-stale'
)
expect(await browser.elementById('long-stale-content').text()).toEqual(
'Long-lived cached content'
)
// The short-lived cached content is NOT part of the App Shell — only
// its loading fallback is.
expect(await browser.locator('#short-stale-content').count()).toBe(0)
expect(await browser.elementById('short-stale-loading').text()).toEqual(
'Loading short-lived content...'
)
})
// After the outer act unblocks the navigation, the short-lived cached
// content streams in with the navigation response, along with the
// dynamic content.
expect(await browser.elementById('short-stale-content').text()).toEqual(
'Short-lived cached content'
)
expect(await browser.elementById('dynamic-content').text()).toEqual(
'Post body for 124'
)
})
it('excludes cached content with a short stale time from a static App Shell', async () => {
// The /static-short-stale/[id] route is fully static and prerendered at
// build time. The short-lived cached content is part of the static
// prerender, but it resolves in the post-shell stage, so it's excluded
// from the App Shell prefix that the client extracts from the prerender
// response and reuses across URLs.
let page: Playwright.Page
const browser = await next.browser('/', {
beforePageLoad(p: Playwright.Page) {
page = p
},
})
const act = createRouterAct(page, { includeAppShellRequests: true })
// Reveal the LinkAccordion for /static-short-stale/1. Like the
// static-posts route, two prefetch responses fire: the per-segment static
// prefetch of /static-short-stale/1 and the runtime shell prefetch.
await act(async () => {
await browser
.elementByCss('input[data-link-accordion="/static-short-stale/1"]')
.click()
}, [
{ includes: 'App shell for static short-stale posts' },
{ includes: 'App shell for static short-stale posts' },
])
await act(async () => {
// Click the link to /static-short-stale/124 — a different param than
// what was prefetched, rendered with prefetch={false}. The cached App
// Shell should render immediately, before the per-URL navigation
// response arrives.
await browser.elementByCss('a[href="/static-short-stale/124"]').click()
// While the navigation response is blocked (we're still in the `act`
// block), the cached App Shell should already be visible, including
// the long-lived cached content.
expect(await browser.elementById('static-shell').text()).toEqual(
'App shell for static short-stale posts'
)
expect(
await browser.elementById('static-long-stale-content').text()
).toEqual('Long-lived cached content')
// The short-lived cached content is NOT part of the App Shell — only
// its loading fallback is.
expect(await browser.locator('#static-short-stale-content').count()).toBe(
0
)
expect(
await browser.elementById('static-short-stale-loading').text()
).toEqual('Loading short-lived content...')
})
// After the outer act unblocks the navigation, the short-lived cached
// content streams in with the navigation response, along with the
// per-URL content.
expect(
await browser.elementById('static-short-stale-content').text()
).toEqual('Short-lived cached content')
expect(await browser.elementById('static-content').text()).toEqual(
'Static post 124'
)
})
describe('root params', () => { describe('root params', () => {
it('includes root params in a runtime App Shell', async () => { it('includes root params in a runtime App Shell', async () => {
let page: Playwright.Page let page: Playwright.Page
......
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