Replace Vercel KV adapter with Vercel Runtime Cache API by bookernath · Pull Request #2475 · bigcommerce/catalyst

bookernath · 2025-07-10T03:32:25Z

What/Why?

Implement Vercel Runtime Cache API as replacement for Vercel KV

Remove Vercel KV and BC KV adapters as they are no longer needed.

As a next step, we could refactor the KV adapters to look more like simple fetch cache adapters, as the only purpose of these adapters is to cache a fetch in middleware.

Testing

After loading up a session in the US for a US-hosted storefront, I did a cold load from Sydney:

https://www.webpagetest.org/result/250822_YiDcYY_8GH/

This cold-load performance shows that Runtime Cache is working well.

Migration

changeset-bot · 2025-07-10T03:32:29Z

🦋 Changeset detected

Latest commit: d151188

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

This PR includes changesets to release 1 package

Name	Type
@bigcommerce/catalyst-core	Minor

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

vercel · 2025-07-10T03:32:31Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
catalyst-b2b	Ready	Preview	Comment	Aug 23, 2025 3:45pm
catalyst-canary	Ready	Preview	Comment	Aug 23, 2025 3:45pm

3 Skipped Deployments

Project	Deployment	Preview	Updated (UTC)
catalyst	Ignored		Aug 23, 2025 3:45pm
catalyst-au	Ignored	Preview	Aug 23, 2025 3:45pm
catalyst-uk	Ignored	Preview	Aug 23, 2025 3:45pm

chanceaclark · 2025-08-20T18:12:13Z

Just noting that we should probably wait for either for Vercel edge runtime support for this or for CF support for nodejs runtime.

Copilot

Pull Request Overview

This PR replaces the Vercel KV adapter with Vercel Runtime Cache API to improve caching performance. The change removes both Vercel KV and BC KV adapters in favor of a new runtime cache implementation that provides better cold-load performance.

Implements new RuntimeCacheAdapter using Vercel's Runtime Cache API
Removes deprecated Vercel KV and BC KV adapters and their dependencies
Updates adapter selection logic to prioritize Runtime Cache for Vercel environments

Reviewed Changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
core/package.json	Updates dependencies, replacing @vercel/kv with @vercel/functions and adding urlpattern-polyfill
core/lib/kv/index.ts	Replaces KV adapter selection logic to prioritize Runtime Cache for Vercel environments
core/lib/kv/adapters/vercel.ts	Removes deprecated Vercel KV adapter implementation
core/lib/kv/adapters/vercel-runtime-cache.ts	Adds new RuntimeCacheAdapter using Vercel Runtime Cache API
core/lib/kv/adapters/upstash.ts	Removes memory caching layer from Upstash adapter
core/lib/kv/adapters/bc.ts	Removes deprecated BC KV adapter implementation
.changeset/chatty-forks-sniff.md	Adds changeset entry for the runtime cache implementation

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-08-23T03:00:35Z

+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      return values as Array<Data | null>;


The type assertion as Array<Data | null> bypasses TypeScript's type checking. Consider using a type guard or proper typing to ensure type safety instead of disabling the linting rule.

Suggested change

// eslint-disable-next-line @typescript-eslint/consistent-type-assertions

return values as Array<Data | null>;

// Return values directly, as they are Array<Data | null>

return values;

migueloller

LGTM 👍🏻

Just had a couple of questions.

migueloller · 2025-08-28T05:35:19Z

    "lru-cache": "^11.1.0",
    "lucide-react": "^0.474.0",
-    "next": "15.4.2-canary.10",
+    "next": "15.5.1-canary.4",


Was upgrading Next.js required to leverage the new Runtime Cache?

No, this was initially desirable when I thought we would move to Node.js middleware as part of this change, so I wanted to be on a version where that feature was considered "stable". Upon review I probably should have decoupled the version bump from this PR once it was clear it was not necessary.

Yeah, I would suggested we do that if we hadn't merged already. Thanks for the explanation 🙏🏻

migueloller · 2025-08-28T05:36:20Z


-import { MemoryKvAdapter } from './memory';
-
-const memoryKv = new MemoryKvAdapter();


How come we removed the memory adapter from the Upstash adapter? This seems unrelated to adding Runtime Cache.

Also, should we have deleted the ./memory.ts file as well?

Memory KV is now handled centrally outside of the individual adapters in the kv/index.ts.

migueloller · 2025-08-28T05:36:44Z

+      );
+
+      // Return null for all keys if Runtime Cache is unavailable
+      return keys.map(() => null);


Is the idea here that returning null behaves as if the cache entries don't exist?

Yes, I want the application to treat this as a cache miss and gracefully continue to load the page even if the cache is degraded. Memory KV will still provide some offload in most scenarios.

bookernath force-pushed the runtime-cache-3 branch from 84db95e to 2268e2d Compare July 10, 2025 03:37

vercel Bot deployed to Preview – catalyst-canary July 10, 2025 03:38 View deployment

bookernath force-pushed the runtime-cache-3 branch from 2268e2d to fd474b6 Compare July 10, 2025 03:52

vercel Bot deployed to Preview – catalyst-canary July 10, 2025 03:54 View deployment

vercel Bot deployed to Preview – catalyst-canary July 10, 2025 04:23 View deployment

bookernath requested a review from Copilot July 10, 2025 04:39

This comment was marked as outdated.

Sign in to view

vercel Bot deployed to Preview – catalyst-canary July 10, 2025 04:50 View deployment

vercel Bot deployed to Preview – catalyst-canary July 10, 2025 16:18 View deployment

vercel Bot deployed to Preview – catalyst-canary July 13, 2025 22:14 View deployment

bookernath force-pushed the runtime-cache-3 branch 4 times, most recently from 2244339 to 520e452 Compare July 14, 2025 14:48

vercel Bot deployed to Preview – catalyst-canary July 14, 2025 14:50 View deployment

bookernath force-pushed the runtime-cache-3 branch from 520e452 to 10bf95a Compare July 30, 2025 22:18

vercel Bot deployed to Preview – catalyst-canary July 30, 2025 22:20 View deployment

bookernath force-pushed the runtime-cache-3 branch from 10bf95a to f6b62bd Compare August 7, 2025 23:06

vercel Bot deployed to Preview – catalyst-canary August 7, 2025 23:07 View deployment

vercel Bot deployed to Preview – catalyst-b2b August 7, 2025 23:08 View deployment

bookernath force-pushed the runtime-cache-3 branch from f6b62bd to cf469dc Compare August 7, 2025 23:09

vercel Bot deployed to Preview – catalyst-canary August 7, 2025 23:10 View deployment

vercel Bot deployed to Preview – catalyst-b2b August 7, 2025 23:10 View deployment

bookernath force-pushed the runtime-cache-3 branch from cf469dc to 9f357fa Compare August 11, 2025 19:29

vercel Bot deployed to Preview – catalyst-b2b August 11, 2025 19:31 View deployment

vercel Bot deployed to Preview – catalyst-canary August 11, 2025 19:31 View deployment

bookernath force-pushed the runtime-cache-3 branch from 9f357fa to ae08fd6 Compare August 14, 2025 18:11

vercel Bot deployed to Preview – catalyst-canary August 14, 2025 18:13 View deployment

vercel Bot deployed to Preview – catalyst-canary August 20, 2025 17:36 View deployment

bookernath force-pushed the runtime-cache-3 branch from 0785523 to f78136d Compare August 20, 2025 18:11

vercel Bot deployed to Preview – catalyst-canary August 20, 2025 18:12 View deployment

vercel Bot deployed to Preview – catalyst-b2b August 20, 2025 18:12 View deployment

bookernath force-pushed the runtime-cache-3 branch 2 times, most recently from 8ad5268 to 204e0be Compare August 22, 2025 16:18

vercel Bot deployed to Preview – catalyst-b2b August 22, 2025 16:20 View deployment

vercel Bot deployed to Preview – catalyst-canary August 22, 2025 16:20 View deployment

bookernath force-pushed the runtime-cache-3 branch 2 times, most recently from 0a1660e to c66dec2 Compare August 22, 2025 16:29

vercel Bot deployed to Preview – catalyst-b2b August 22, 2025 16:31 View deployment

vercel Bot deployed to Preview – catalyst-canary August 22, 2025 16:32 View deployment

bookernath force-pushed the runtime-cache-3 branch from c66dec2 to 6bc63bc Compare August 22, 2025 16:33

vercel Bot deployed to Preview – catalyst-canary August 22, 2025 16:34 View deployment

vercel Bot deployed to Preview – catalyst-b2b August 22, 2025 16:34 View deployment

bookernath force-pushed the runtime-cache-3 branch from 6bc63bc to 6b1e018 Compare August 23, 2025 02:52

vercel Bot deployed to Preview – catalyst-canary August 23, 2025 02:53 View deployment

vercel Bot deployed to Preview – catalyst-b2b August 23, 2025 02:53 View deployment

bookernath requested a review from Copilot August 23, 2025 03:00

Copilot AI reviewed Aug 23, 2025

View reviewed changes

bookernath force-pushed the runtime-cache-3 branch from 6b1e018 to 30caa5f Compare August 23, 2025 10:46

vercel Bot deployed to Preview – catalyst-canary August 23, 2025 10:47 View deployment

vercel Bot deployed to Preview – catalyst-b2b August 23, 2025 10:47 View deployment

feat: replace Vercel KV adapter with Vercel Runtime Cache API

d151188

bookernath force-pushed the runtime-cache-3 branch from 30caa5f to d151188 Compare August 23, 2025 15:43

jkanive approved these changes Aug 23, 2025

View reviewed changes

github-actions Bot mentioned this pull request Aug 22, 2025

Version Packages (canary) #2522

Merged

migueloller reviewed Aug 28, 2025

View reviewed changes

github-actions Bot mentioned this pull request Aug 28, 2025

Version Packages (canary) bookernath/catalyst#1

Open

		// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
		return values as Array<Data \| null>;


		import { MemoryKvAdapter } from './memory';

		const memoryKv = new MemoryKvAdapter();

Conversation

bookernath commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why?

Testing

Migration

Uh oh!

changeset-bot Bot commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

chanceaclark commented Aug 20, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Aug 23, 2025

Choose a reason for hiding this comment

Uh oh!

migueloller left a comment

Choose a reason for hiding this comment

Uh oh!

migueloller Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

bookernath Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

migueloller Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

migueloller Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

bookernath Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

migueloller Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

bookernath Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

bookernath commented Jul 10, 2025 •

edited

Loading

changeset-bot Bot commented Jul 10, 2025 •

edited

Loading

vercel Bot commented Jul 10, 2025 •

edited

Loading