Implement persistent data cache option and update cache key logic #920

conico974 · 2025-07-02T09:34:10Z

Introduce a new option to maintain the data cache across deployments and adjust cache key generation to reflect this change. Fix issues related to tag caching and ensure proper handling of cache keys in various scenarios.

BREAKING CHANGE: Incremental cache keys are now an object of type CacheKey instead of a string. The new type includes properties like baseKey, buildId, and cacheType. Build_id is automatically provided according to the cache type and the dangerous.persistentDataCache option. Up to the Incremental Cache implementation to use it as they see fit.

changeset-bot · 2025-07-02T09:34:14Z

🦋 Changeset detected

Latest commit: 4710f0a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@opennextjs/aws	Minor
app-pages-router	Patch
app-router	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vicb · 2025-07-02T09:38:16Z

Is the fix related to the other changes? (Maybe clarify in the PR description)

There are conflicts.

I'll take a look later today

conico974 · 2025-07-02T09:41:36Z

My bad i rebased on the wrong branch... I'll fix it

pkg-pr-new · 2025-07-02T09:58:52Z

Open in StackBlitz

pnpm add https://pkg.pr.new/@opennextjs/aws@920

commit: 4710f0a

packages/open-next/src/types/open-next.ts

packages/open-next/src/adapters/cache.ts

packages/open-next/src/utils/cache.ts

.changeset/slow-walls-allow.md

packages/open-next/src/utils/cache.ts

packages/open-next/src/adapters/cache.ts

vicb

Nice!

I added a few minor comments but changes look good.

Probably we should doc that overrides should not use the BUILD_ID to enable the feature.

I question:

For composable cache, we use

globalThis.tagCache.hasBeenRevalidated(
          result.value.tags,
          result.lastModified,

vs hasBeenRevalidated from utils - any particular reason. Would be nice to add comments.

vicb · 2025-07-02T10:56:46Z

packages/open-next/src/adapters/cache.ts

    try {
+      const key = createCacheKey(baseKey, true);
      const cachedEntry = await globalThis.incrementalCache.get(key, "fetch");

      if (cachedEntry?.value === undefined) return null;

      const _tags = [...(tags ?? []), ...(softTags ?? [])];
      const _lastModified = cachedEntry.lastModified ?? Date.now();
      const _hasBeenRevalidated = await hasBeenRevalidated(


Maybe we should add a comment explaining why the base key is used (inline + on the method)?

Re-opening.
Could we expand on why this is not using the obj key?

packages/open-next/src/adapters/composable-cache.ts

packages/open-next/src/overrides/incrementalCache/s3-lite.ts

packages/open-next/src/types/open-next.ts

conico974 · 2025-07-02T11:35:03Z

I'll update the PR with the changes later today

vicb · 2025-07-02T12:12:20Z

Thought: In the Couldflare adapter the cache key is prefix/build-id/hash(key)

build-id is used to partition the cache
we need to hash(...) to fit within the allowed length and chars

That will become harder to do with this PR.

There are multiple ways to solve this but while thinking about this I was wondering if the change could not be implemented by only updating the overrides? i.e. we could pass a key that is independent of the BUILD_ID and then up to the override to add the build Id or not.

conico974 · 2025-07-02T14:05:35Z

There are multiple ways to solve this but while thinking about this I was wondering if the change could not be implemented by only updating the overrides? i.e. we could pass a key that is independent of the BUILD_ID and then up to the override to add the build Id or not.

That's exactly what was done before (except for the composable cache).
I feel like this is something that we need to handle here, not the override itself. It feels weird to have to do the same thing on every single override.

One option would be to have a special type as a key like

interface CacheKey {
  baseKey: string,
  buildId?:string
}

You can then decide what you do with it.

vicb · 2025-07-02T14:59:47Z

One option would be to have a special type as a key like

+1

It could also help alleviate the confusion between key: string and baseKey: string

vicb · 2025-07-04T10:34:05Z

.changeset/slow-walls-allow.md

+
+Add an option to keep the data cache persistent between deployments.
+
+BREAKING CHANGE: Incremental cache keys are now an object of type `CacheKey` instead of a string. The new type includes properties like `baseKey`, `buildId`, and `cacheType`. Build_id is automatically provided according to the cache type and the `dangerous.persistentDataCache` option. Up to the Incremental Cache implementation to use it as they see fit.


Explicitly say that the overrides should be updated?

(Adding this text to the PR description)

vicb · 2025-07-04T10:37:05Z

packages/open-next/src/adapters/cache.ts

-            await globalThis.incrementalCache.set(
-              key,
-              {
+              await globalThis.incrementalCache.set(key, {


Look like this is a formatting only diff?

vicb · 2025-07-04T10:39:53Z

packages/open-next/src/adapters/composable-cache.ts

+ * @param key The composable cache key
+ * @returns The composable cache key.
+ */
+function getComposableCacheKey(key: string): CacheKey<"composable"> {


Could this be merged into createCacheKey?

Yeah probably

vicb · 2025-07-04T10:47:20Z

packages/open-next/src/adapters/composable-cache.ts

    try {
+      const cacheKey = getComposableCacheKey(key);


Would it make sense to move that l45 and use key on l42 and 43?

edit:
Oh actually I think that's what we want as they might differ.
Should we add a comment warning that key should not be used?

edit2:
But I guess that I have the same question as the tag cache: why wouldn't we use the build?

Here it doesn't really matter, it's in memory anyway.
For the tag cache, technically we don't need the build_id as it is time based.
There is one case actually when it is useful to have the build_id, it's for more complex deployment (like blue/green).
I think what make sense is just to pass the CacheKey to the tag cache as well and let the implementation decides.
For the default one, I think we should just follow the persistentDataCache option
WDYT ?

vicb · 2025-07-04T10:54:13Z

packages/open-next/src/overrides/incrementalCache/fs-dev.ts


 const getCacheKey = (key: string) => {
  return path.join(basePath, `${key}.cache`);
 };

 const cache: IncrementalCache = {
  name: "fs-dev",
-  get: async (key: string) => {
-    const fileData = await fs.readFile(getCacheKey(key), "utf-8");
+  get: async ({ baseKey }) => {


Suggested change

get: async ({ baseKey }) => {

get: async (cacheKey: CacheKey) => {

// This cache is always shared across build (the build id is not used)

const { baseKey } = cacheKey;

vicb · 2025-07-04T10:56:52Z

packages/open-next/src/overrides/incrementalCache/multi-tier-ddb-s3.ts

-  const { NEXT_BUILD_ID } = process.env;
-  return `__meta_${NEXT_BUILD_ID}_${key}`;
+const buildDynamoKey = (key: CacheKey<CacheEntryType>) => {
+  return `__meta_${key.buildId ? `${key.buildId}_` : ""}${key.baseKey}`;


nit: could this be simplified?
not the exact same output as the current code but it should not matter?

Suggested change

return `__meta_${key.buildId ? `${key.buildId}_` : ""}${key.baseKey}`;

return `__meta_${key.buildId ?? ""}_${key.baseKey}`;

vicb · 2025-07-04T11:06:45Z

packages/open-next/src/utils/cache.ts

+    cacheType: type,
+    buildId: undefined,
+    baseKey: key,
+  } as CacheKey<CacheType>;


is as CacheKey<CacheType> needed here?

vicb · 2025-07-04T11:08:41Z

packages/open-next/src/utils/cache.ts

+  // We always prepend the build ID to the cache key for ISR/SSG cache entry
+  // For data cache, we only prepend the build ID if the persistentDataCache is not enabled


"prepend" do not sound right any more.

would be great to update the comments and move to their corresponding case.

Nicolas Dorseuil added 4 commits July 2, 2025 11:47

compute cache key according to persistentDataCache

02159d3

remove build id from cache keys in overrides

b989b0c

fix for tag cache

2e38e4c

changeset

a8b69ff

conico974 force-pushed the feat/persistent-data-cache branch from 74ae605 to a8b69ff Compare July 2, 2025 09:58

fix linting

456286b