Skip to content

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

Closed

Description

@jeroendegloire

Versions: @leejpsd/nextjs-cache-handler 0.4.2 and 1.0.0, Next.js 16.4.2

What happens

seedBuildOutput() writes App Router APP_PAGE records under the bare pathname from prerender-manifest.json (e.g. /nl/investeren).

Next.js 16.4+ Full Route Cache lookups use meta.routeCache.key from the prerender .meta file, shaped like:

/route-cache/APP_PAGE/<hash>/$/nl/investeren

After a successful seed, Redis has a key the runtime never reads → first request is still x-nextjs-cache: MISS until the page is regenerated and written under the route-cache key.

Expected

An opt-in (or documented) way for seed to write under meta.routeCache.key when present, so a cold Redis after deploy can serve Full Route Cache HITs on first request.

Proposed API

seedBuildOutput({
  …,
  preferRouteCacheKey: true, // App Router only; falls back to pathname if meta.routeCache.key missing
})

CLI: npx nextjs-cache-handler seed --prefer-route-cache-key

Default stays pathname keys for backwards compatibility with older Next / custom readers.

Workaround

We currently ship this as a pnpm patch on 0.4.2 and pass preferRouteCacheKey: true from our seed script.

Activity

  1. leejpsd commented on Nov 13, 2026

    @leejpsd
    Owner

    Sorry for the delay here as well, and thanks for tracking this down. You were right that the seed wrote keys the runtime never reads. Fixed in #21 and released in 1.0.2.

    Two differences from the proposal:

    • It is automatic, not opt-in. When routeCache.key is in the build's .meta, that is the only key the runtime will ask for, so the seed uses it whenever it is present. There is no option or CLI flag.
    • Pages Router is covered too. Next writes the same metadata to server/pages/*.meta.

    One detail: the scoped keys arrived in 16.3.8, not 16.4, so 16.3.8+ was affected as well.

    Verified with next build, seed, next start on 16.2.4, 16.3.8 and 16.4.6: the first request is a HIT for App Router, SSG and Pages routes. While testing the older version I also found that the root route was seeded under / instead of /index and was never read. That is fixed in the same release.

    If your seed script passes preferRouteCacheKey: true, please remove it along with the patch. The option does not exist in 1.0.2.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions