docs: update revalidatePath & fix cache debug logic

[ztanner]

When revalidating a page that corresponds with a dynamic path and when using the “type” parameter, eg revalidatePath(“/dynamic/1”, “page”) corresponding with /dynamic/[id], the wrong cache tags would be checked to determine if a revalidation occurred.

This is because the “derived” cache tags created for a /dynamic/[id]/page are:


• /dynamic/[id]/layout
• /dynamic/[id]/page

Additionally, a tag is added for the current canonical URL, so the final tag would be:

• /dynamic/1

Thus a fetch on /dynamic/1 would be tagged with the following:

• /layout
• /dynamic/layout
• /dynamic/[id]/layout
• /dynamic/[id]/page
• /dynamic/1

Calling revalidatePath(“/dynamic/1”, “page”) would signal to revalidate caches tagged /dynamic/1/page in the current logic. However, this tag doesn’t exist given the above, so it would be a no-op and wouldn't properly re-invoke the fetch.

This updates the docs to explicitly call out that if you are attempting to revalidate a path that corresponds with a dynamic page, that you should not provide a "type" argument.

Fixes #62071
Closes NEXT-3302

[ztanner]

• docs: update revalidatePath & fix cache debug logic #65365 👈
• 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]

Failing test suites

Commit: 3b43d6d

TURBOPACK=1 pnpm test-dev test/e2e/prerender.test.ts (turbopack)

• Prerender > should log error in console and browser in development mode

Expand output

● Prerender › should log error in console and browser in development mode

page.waitForSelector: Timeout 60000ms exceeded.
Call log:
  - waiting for locator('#after-change')

  421 |     return this.chain(() => {
  422 |       return page
> 423 |         .waitForSelector(selector, { timeout, state: 'attached' })
      |          ^
  424 |         .then(async (el) => {
  425 |           // it seems selenium waits longer and tests rely on this behavior
  426 |           // so we wait for the load event fire before returning

  at waitForSelector (lib/browsers/playwright.ts:423:10)

Read more about building and testing Next.js in contributing.md.

[ztanner]

This change should be reviewed without whitespace. I updated this to be consistent with how it's structured in fetch-cache, to prevent debug mode from printing:

not using memory store for fetch cache

Even though it was, because the memory cache had already been instantiated.

[ijjk]

Stats from current PR

Default Build (Increase detected ⚠️)

General Overall increase ⚠️

	vercel/next.js canary	vercel/next.js 05-04-fix_ensure_revalidatePath_consistently_revalidates_fetches_on_dynamic_routes	Change
buildDuration	15.5s	13.8s	N/A
buildDurationCached	8.1s	6.8s	N/A
nodeModulesSize	360 MB	360 MB	⚠️ +944 B
nextStartRea..uration (ms)	407ms	412ms	N/A

Client Bundles (main, webpack)

	vercel/next.js canary	vercel/next.js 05-04-fix_ensure_revalidatePath_consistently_revalidates_fetches_on_dynamic_routes	Change
1103-HASH.js gzip	31.9 kB	31.9 kB	N/A
1a9f679d-HASH.js gzip	53.5 kB	53.5 kB	N/A
335-HASH.js gzip	5.05 kB	5.05 kB	✓
7953.HASH.js gzip	169 B	169 B	✓
framework-HASH.js gzip	45.2 kB	45.2 kB	✓
main-app-HASH.js gzip	231 B	228 B	N/A
main-HASH.js gzip	31.6 kB	31.6 kB	N/A
webpack-HASH.js gzip	1.65 kB	1.65 kB	N/A
Overall change	50.4 kB	50.4 kB	✓

Legacy Client Bundles (polyfills)

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

Client Pages

	vercel/next.js canary	vercel/next.js 05-04-fix_ensure_revalidatePath_consistently_revalidates_fetches_on_dynamic_routes	Change
_app-HASH.js gzip	192 B	193 B	N/A
_error-HASH.js gzip	192 B	192 B	✓
amp-HASH.js gzip	507 B	511 B	N/A
css-HASH.js gzip	341 B	343 B	N/A
dynamic-HASH.js gzip	2.52 kB	2.52 kB	✓
edge-ssr-HASH.js gzip	266 B	265 B	N/A
head-HASH.js gzip	362 B	365 B	N/A
hooks-HASH.js gzip	392 B	392 B	✓
image-HASH.js gzip	4.27 kB	4.27 kB	✓
index-HASH.js gzip	268 B	268 B	✓
link-HASH.js gzip	2.69 kB	2.7 kB	N/A
routerDirect..HASH.js gzip	329 B	328 B	N/A
script-HASH.js gzip	397 B	397 B	✓
withRouter-HASH.js gzip	324 B	324 B	✓
1afbb74e6ecf..834.css gzip	106 B	106 B	✓
Overall change	8.47 kB	8.47 kB	✓

Client Build Manifests

	vercel/next.js canary	vercel/next.js 05-04-fix_ensure_revalidatePath_consistently_revalidates_fetches_on_dynamic_routes	Change
_buildManifest.js gzip	483 B	485 B	N/A
Overall change	0 B	0 B	✓

Rendered Page Sizes

	vercel/next.js canary	vercel/next.js 05-04-fix_ensure_revalidatePath_consistently_revalidates_fetches_on_dynamic_routes	Change
index.html gzip	528 B	526 B	N/A
link.html gzip	541 B	540 B	N/A
withRouter.html gzip	524 B	522 B	N/A
Overall change	0 B	0 B	✓

Edge SSR bundle Size

	vercel/next.js canary	vercel/next.js 05-04-fix_ensure_revalidatePath_consistently_revalidates_fetches_on_dynamic_routes	Change
edge-ssr.js gzip	94.9 kB	94.8 kB	N/A
page.js gzip	182 kB	182 kB	N/A
Overall change	0 B	0 B	✓

Middleware size

	vercel/next.js canary	vercel/next.js 05-04-fix_ensure_revalidatePath_consistently_revalidates_fetches_on_dynamic_routes	Change
middleware-b..fest.js gzip	621 B	624 B	N/A
middleware-r..fest.js gzip	156 B	156 B	✓
middleware.js gzip	25.7 kB	25.7 kB	N/A
edge-runtime..pack.js gzip	839 B	839 B	✓
Overall change	995 B	995 B	✓

Next Runtimes

	vercel/next.js canary	vercel/next.js 05-04-fix_ensure_revalidatePath_consistently_revalidates_fetches_on_dynamic_routes	Change
app-page-exp...dev.js gzip	171 kB	171 kB	✓
app-page-exp..prod.js gzip	98.8 kB	98.8 kB	✓
app-page-tur..prod.js gzip	100 kB	100 kB	✓
app-page-tur..prod.js gzip	94.6 kB	94.6 kB	✓
app-page.run...dev.js gzip	157 kB	157 kB	✓
app-page.run..prod.js gzip	93.3 kB	93.3 kB	✓
app-route-ex...dev.js gzip	21.5 kB	21.5 kB	✓
app-route-ex..prod.js gzip	15.3 kB	15.3 kB	✓
app-route-tu..prod.js gzip	15.3 kB	15.3 kB	✓
app-route-tu..prod.js gzip	15 kB	15 kB	✓
app-route.ru...dev.js gzip	21.4 kB	21.4 kB	✓
app-route.ru..prod.js gzip	15 kB	15 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	21.5 kB	21.5 kB	✓
pages.runtim...dev.js gzip	22.1 kB	22.1 kB	✓
pages.runtim..prod.js gzip	21.5 kB	21.5 kB	✓
server.runti..prod.js gzip	51.8 kB	51.8 kB	N/A
Overall change	913 kB	913 kB	✓

build cache Overall increase ⚠️

	vercel/next.js canary	vercel/next.js 05-04-fix_ensure_revalidatePath_consistently_revalidates_fetches_on_dynamic_routes	Change
0.pack gzip	1.62 MB	1.62 MB	⚠️ +841 B
index.pack gzip	114 kB	113 kB	N/A
Overall change	1.62 MB	1.62 MB	⚠️ +841 B

Diff details

Diff for edge-ssr.js

Diff too large to display

Diff for server.runtime.prod.js

Diff too large to display

Commit: 3b43d6d