add experimental client router cache config

[ztanner]

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

// 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 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

[ztanner]

• add experimental client router cache config #62856 👈
• Fix instant loading states after invalidating prefetch cache #63256
• Store loading data in CacheNode #62346 : 1 other dependent PR (#62347 )
• Pass whole prefetch entry rather than status property #62345
• canary

This stack of pull requests is managed by Graphite. Learn more about stacking.

Join @ztanner and the rest of your teammates on Graphite

[ijjk]

Tests Passed

[ijjk]

Stats from current PR

Default Build (Increase detected ⚠️)

General Overall increase ⚠️

	vercel/next.js canary	vercel/next.js 03-04-add_experimental_client_router_cache_config	Change
buildDuration	14s	14s	N/A
buildDurationCached	7.6s	6.2s	N/A
nodeModulesSize	199 MB	199 MB	⚠️ +10.7 kB
nextStartRea..uration (ms)	402ms	396ms	N/A

Client Bundles (main, webpack)

	vercel/next.js canary	vercel/next.js 03-04-add_experimental_client_router_cache_config	Change
2453-HASH.js gzip	31.4 kB	31.3 kB	N/A
3304.HASH.js gzip	181 B	181 B	✓
3f784ff6-HASH.js gzip	53.7 kB	53.7 kB	✓
8299-HASH.js gzip	5.04 kB	5.04 kB	N/A
framework-HASH.js gzip	45.2 kB	45.2 kB	✓
main-app-HASH.js gzip	240 B	242 B	N/A
main-HASH.js gzip	32.2 kB	32.2 kB	N/A
webpack-HASH.js gzip	1.68 kB	1.68 kB	N/A
Overall change	99 kB	99 kB	✓

Legacy Client Bundles (polyfills)

	vercel/next.js canary	vercel/next.js 03-04-add_experimental_client_router_cache_config	Change
polyfills-HASH.js gzip	31 kB	31 kB	✓
Overall change	31 kB	31 kB	✓

Client Pages

	vercel/next.js canary	vercel/next.js 03-04-add_experimental_client_router_cache_config	Change
_app-HASH.js gzip	196 B	197 B	N/A
_error-HASH.js gzip	184 B	184 B	✓
amp-HASH.js gzip	505 B	505 B	✓
css-HASH.js gzip	324 B	325 B	N/A
dynamic-HASH.js gzip	2.5 kB	2.5 kB	N/A
edge-ssr-HASH.js gzip	258 B	258 B	✓
head-HASH.js gzip	352 B	352 B	✓
hooks-HASH.js gzip	370 B	371 B	N/A
image-HASH.js gzip	4.21 kB	4.21 kB	✓
index-HASH.js gzip	259 B	259 B	✓
link-HASH.js gzip	2.67 kB	2.67 kB	N/A
routerDirect..HASH.js gzip	314 B	312 B	N/A
script-HASH.js gzip	386 B	386 B	✓
withRouter-HASH.js gzip	309 B	309 B	✓
1afbb74e6ecf..834.css gzip	106 B	106 B	✓
Overall change	6.57 kB	6.57 kB	✓

Client Build Manifests

	vercel/next.js canary	vercel/next.js 03-04-add_experimental_client_router_cache_config	Change
_buildManifest.js gzip	481 B	484 B	N/A
Overall change	0 B	0 B	✓

Rendered Page Sizes

	vercel/next.js canary	vercel/next.js 03-04-add_experimental_client_router_cache_config	Change
index.html gzip	530 B	528 B	N/A
link.html gzip	541 B	540 B	N/A
withRouter.html gzip	525 B	522 B	N/A
Overall change	0 B	0 B	✓

Edge SSR bundle Size

	vercel/next.js canary	vercel/next.js 03-04-add_experimental_client_router_cache_config	Change
edge-ssr.js gzip	95.3 kB	95.4 kB	N/A
page.js gzip	3.04 kB	3.06 kB	N/A
Overall change	0 B	0 B	✓

Middleware size

	vercel/next.js canary	vercel/next.js 03-04-add_experimental_client_router_cache_config	Change
middleware-b..fest.js gzip	627 B	625 B	N/A
middleware-r..fest.js gzip	151 B	151 B	✓
middleware.js gzip	25.5 kB	25.5 kB	N/A
edge-runtime..pack.js gzip	839 B	839 B	✓
Overall change	990 B	990 B	✓

Next Runtimes

	vercel/next.js canary	vercel/next.js 03-04-add_experimental_client_router_cache_config	Change
app-page-exp...dev.js gzip	170 kB	170 kB	✓
app-page-exp..prod.js gzip	97 kB	97 kB	✓
app-page-tur..prod.js gzip	98.8 kB	98.8 kB	✓
app-page-tur..prod.js gzip	93 kB	93 kB	✓
app-page.run...dev.js gzip	144 kB	144 kB	✓
app-page.run..prod.js gzip	91.5 kB	91.5 kB	✓
app-route-ex...dev.js gzip	21.4 kB	21.4 kB	✓
app-route-ex..prod.js gzip	15.1 kB	15.1 kB	✓
app-route-tu..prod.js gzip	15.1 kB	15.1 kB	✓
app-route-tu..prod.js gzip	14.8 kB	14.8 kB	✓
app-route.ru...dev.js gzip	21 kB	21 kB	✓
app-route.ru..prod.js gzip	14.8 kB	14.8 kB	✓
pages-api-tu..prod.js gzip	9.55 kB	9.55 kB	✓
pages-api.ru...dev.js gzip	9.82 kB	9.82 kB	✓
pages-api.ru..prod.js gzip	9.55 kB	9.55 kB	✓
pages-turbo...prod.js gzip	22.5 kB	22.5 kB	✓
pages.runtim...dev.js gzip	23.1 kB	23.1 kB	✓
pages.runtim..prod.js gzip	22.4 kB	22.4 kB	✓
server.runti..prod.js gzip	51 kB	51 kB	✓
Overall change	944 kB	944 kB	✓

build cache Overall increase ⚠️

	vercel/next.js canary	vercel/next.js 03-04-add_experimental_client_router_cache_config	Change
0.pack gzip	1.58 MB	1.58 MB	⚠️ +1.83 kB
index.pack gzip	106 kB	106 kB	N/A
Overall change	1.58 MB	1.58 MB	⚠️ +1.83 kB

Diff details

Diff for page.js

Diff too large to display

Diff for middleware.js

Diff too large to display

Diff for edge-ssr.js

Diff too large to display

Diff for 2453-HASH.js

Diff too large to display

Commit: 3098fd1

[jrnxf]

may I kindly ask this receive some attention? a lot of us are waiting on this!

[Enngage]

same here. Would be nice if this got merged and released

[Cnsbmkpsr]

Same here, this fix is very important

[eremenko1]

upd pls