Skip to content

fix(seed): write routes under the key the runtime actually looks up - #21

Merged
leejpsd merged 1 commit into
mainfrom
fix/seed-route-cache-key
Nov 13, 2026
Merged

leejpsd merged 1 commit into
mainfrom
fix/seed-route-cache-key

Conversation

@leejpsd

@leejpsd leejpsd commented Nov 13, 2026

Copy link
Copy Markdown
Owner

Closes #16. Supersedes #18.

Two independent problems made seeded routes unreadable.

1. Next.js 16.3.8+: route-scoped keys (#16)

From 16.3.8, response-cache keys are scoped by source route (/route-cache/<KIND>/<hash>/$/<path>) and a custom cache handler is never asked for a bare pathname. Seeds written under the pathname were never read, so the first request after a deploy was still a MISS.

The build records the exact key in each artifact's .meta (routeCache.key). App Router and Pages Router routes are now seeded under that key whenever it is present. This is automatic: when the key is in the build output, it is the only key that runtime will read, so there is nothing to opt into.

2. Next.js < 16.3.8: root route key

Older versions look routes up under normalizePagePath, where / is /index. The seed wrote the root route under /, so the home page seed was never read. Routes starting with /index were also read from the wrong artifact files. The artifact path and the fallback key now follow the same normalization.

Verification

Unit: 190 passed (new cases fail on current main).

End to end, real Redis, next build → seed → next start → first request:

Next.js / /blog/a (SSG) /legacy (Pages)
16.2.4 HIT (was MISS) HIT HIT
16.3.8 HIT (was MISS) HIT (was MISS) HIT (was MISS)
16.4.6 HIT (was MISS) HIT (was MISS) HIT (was MISS)

Known limit: a page literally located at /index (app/index/page.tsx) is still not served from a seed. On 16.3.8+ the key recorded in its build .meta differs from the key the runtime requests for that URL, and before 16.3.8 Next resolves that URL to the root entry. Both happen inside Next and are unrelated to seeding.

Thanks to @jeroendegloire for the report and the original patch in #18.

Two independent problems made seeded routes unreadable.

Next.js 16.3.8+ scopes response-cache keys by source route
(/route-cache/<KIND>/<hash>/$/<path>) and never asks a custom cache
handler for a bare pathname. The build records the exact key in each
artifact's .meta (routeCache.key). App Router and Pages Router routes
are now seeded under that key when it is present.

Before 16.3.8, routes are stored and looked up under Next's normalized
page path, where / is /index. The seed wrote the root route under /, so
it was never read, and read /index-prefixed routes from the wrong
files. The artifact path and the fallback key now follow
normalizePagePath.

No option is needed for either case.

Closes #16

Co-authored-by: jeroendegloire <13023723+jeroendegloire@users.noreply.github.com>
@leejpsd
leejpsd merged commit 3a57a0b into main Nov 13, 2026
5 checks passed
@leejpsd
leejpsd deleted the fix/seed-route-cache-key branch November 13, 2026 06:37
@github-actions github-actions Bot mentioned this pull request Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

seedBuildOutput writes pathname keys; Next 16.4+ Full Route Cache reads meta.routeCache.key

1 participant