[GH-ISSUE #562] Populating remote cache during deployment #116

New issue

Open

opened 2026-05-06 12:37:21 +02:00 by BreizhHardware · 1 comment

BreizhHardware commented

2026-05-06 12:37:21 +02:00

Owner

Originally created by @james-elicx on GitHub (Mar 16, 2026).
Original GitHub issue: https://github.com/cloudflare/vinext/issues/562

If an application has configured a remote cache handler like Workers KV, and has pre-rendered assets, those should automatically populate KV using Wrangler at deploy-time.

For KV, see the OpenNext implementation.

Originally created by @james-elicx on GitHub (Mar 16, 2026). Original GitHub issue: https://github.com/cloudflare/vinext/issues/562 If an application has configured a remote cache handler like Workers KV, and has pre-rendered assets, those should automatically populate KV using Wrangler at deploy-time. For KV, see the OpenNext implementation.

BreizhHardware added the

enhancement

label

2026-05-06 12:37:21 +02:00

BreizhHardware commented

2026-05-06 12:37:22 +02:00

Author

Owner

@james-elicx commented on GitHub (Mar 24, 2026):

Sharing my current thoughts below.

A mechanism to bulk upload to a remote cache must be supported for it to be viable for large apps.

I say this because using the pre-existing set(...) method on the cache handler would be rather inefficient if a site pre-rendered thousands of apps, as it would be uploading entries one-by-one, instead of in batches. Further, using Workers deployments as an example, the handler may be context-dependent in its ability to work - the KV handler expected to run in workerd with its binding available, which would require spinning up a worker on the fly - something Vinext shouldn't have knowledge of.

Some options I've been thinking of...

I would caveat with that I think we should look to move away from the setCacheHandler method we currently use for Workers in general.

Population method defined on cache handlers

We could consider building on top of the existing cache handler structure and adding an optional method for populating.

This has the benefit of being fully-compatible with a user's choice to define a cache handler using the Next.js config option to point to a path for a custom handler. It also wouldn't be a hard-requirement for an adapter, and would be optional, enabling other cache handlers to be used without issue.

This could potentially look something like follows

export class KVCacheHandler implements CacheHandler {
	constructor() {}
	async get() {}
	async set() {}
	async revalidateTag() {}

	static async populate(manifest: PrerenderManifest) {
		// call api to bulk populate based on prerender manifest contents
	}
}

There is a significant concern with this though - the method would likely get bundled as part of the cache handler in the final bundle we build. In the case of Workers, this could be problematic. If it depended on something like Wrangler or rclone, this could bloat the bundle and include things incompatible with the deployment target.

Vinext-driven config

Another option we could explore is having the Vinext plugin support config options for the cache, which is something I've been thinking about a bit recently. It would allow separate things to be provided for the cache itself, and the population method.

Could potentially look something like follows

import { KVCacheHandler, populateKVNamespace } from '@vinext/cloudflare/kv-cache-handler'

vinext({
	cache: {
		handler: KVCacheHandler,
		populateMethod: populateKVNamespace,
	}
	prerender: {
		mode: 'all', // 'all' | 'traffic-based'
	}
})

This would, however, mean that we're defining cache handlers outside of Next.js config in order for them to fully work, which isn't necessary a bad thing given how it's they're intended to be used...

This would have the benefit of giving more control and configurability potential, and could tie in with bringing prerender configuration into the Vinext config. Further, it would probably work well if we bring deployment adapters into the Vinext config in the future.

Not 100% sold on the schema in the example though - could be refined a bit potentially.

Other options?

Completely open to other options as well - trying to get the ball rolling and find an avenue that would work long-term!

@james-elicx commented on GitHub (Mar 24, 2026): Sharing my current thoughts below. A mechanism to bulk upload to a remote cache **must** be supported for it to be viable for large apps. I say this because using the pre-existing `set(...)` method on the cache handler would be rather inefficient if a site pre-rendered thousands of apps, as it would be uploading entries one-by-one, instead of in batches. Further, using Workers deployments as an example, the handler may be context-dependent in its ability to work - the KV handler expected to run in workerd with its binding available, which would require spinning up a worker on the fly - something Vinext shouldn't have knowledge of. Some options I've been thinking of... I would caveat with that I think we should look to move away from the `setCacheHandler` method we currently use for Workers in general. ### Population method defined on cache handlers We could consider building on top of the existing cache handler structure and adding an optional method for populating. This has the benefit of being fully-compatible with a user's choice to define a cache handler using the Next.js config option to point to a path for a custom handler. It also wouldn't be a hard-requirement for an adapter, and would be optional, enabling other cache handlers to be used without issue. This could potentially look something like follows ```ts export class KVCacheHandler implements CacheHandler { constructor() {} async get() {} async set() {} async revalidateTag() {} static async populate(manifest: PrerenderManifest) { // call api to bulk populate based on prerender manifest contents } } ``` There is a significant concern with this though - the method would likely get bundled as part of the cache handler in the final bundle we build. In the case of Workers, this could be problematic. If it depended on something like Wrangler or rclone, this could bloat the bundle and include things incompatible with the deployment target. ### Vinext-driven config Another option we could explore is having the Vinext plugin support config options for the cache, which is something I've been thinking about a bit recently. It would allow separate things to be provided for the cache itself, and the population method. Could potentially look something like follows ```ts import { KVCacheHandler, populateKVNamespace } from '@vinext/cloudflare/kv-cache-handler' vinext({ cache: { handler: KVCacheHandler, populateMethod: populateKVNamespace, } prerender: { mode: 'all', // 'all' | 'traffic-based' } }) ``` This would, however, mean that we're defining cache handlers outside of Next.js config in order for them to fully work, which isn't necessary a bad thing given how it's they're intended to be used... This would have the benefit of giving more control and configurability potential, and could tie in with bringing prerender configuration into the Vinext config. Further, it would probably work well if we bring deployment adapters into the Vinext config in the future. Not 100% sold on the schema in the example though - could be refined a bit potentially. ### Other options? Completely open to other options as well - trying to get the ball rolling and find an avenue that would work long-term!

BreizhHardware referenced this issue

2026-05-06 12:39:12 +02:00

[PR #116] [CLOSED] feat: fumadocs docs #324