Skip to content

Commit edef7fd

Browse files
morinokamiclaude
andauthored
fix(deploy): serve framework static files without starting the Worker (#804)
Closes #794 `void deploy --platform cloudflare` writes `assets.run_worker_first: true` for SvelteKit, Nuxt, Analog, and Astro. Every request starts the Worker, including fingerprinted build files (`/_astro/*`, `/_app/immutable/*`, `/_nuxt/*`) and prerendered pages, and each one counts as a Worker request. The framework Worker only passes those requests to `ASSETS`. The write also replaces a `run_worker_first` set in `cloudflare.assets` in `void.config.ts`, although `docs/reference/config.md` says Void passes `cloudflare` fields through. Each framework's own Cloudflare config, and managed framework deploys, leave `run_worker_first` unset, so Cloudflare serves files without starting the Worker. ## Fix Without a `run_worker_first` in `void.config.ts`, framework deploys now write `["/__void", "/__void/*"]`: ``` request ──► Workers Static Assets │ ├─ /__void, /__void/* ──► Worker ├─ file matches ─────────► served, no Worker └─ no file ──────────────► Worker (not_found_handling: none) ``` - Server-rendered pages and endpoints have no file, so they still reach the Worker. Void's readiness, job, and queue endpoints always do. - A `run_worker_first` set in `void.config.ts` is written as is. `true` keeps the previous routing. - The setting is read from `void.config.ts`, not from the generated config. `void.lock.json` can hold the `true` an earlier deploy wrote, and the generated config is restored from it. - `writeCloudflareFrameworkDeployConfig` in `@void/deploy-cloudflare` takes an optional `runWorkerFirst`. It still defaults to `true`. - `docs/guide/edge/static-assets.md` describes the default and the setting. Running the Worker first gave these files nothing extra: - Void's framework wrapper handles only `/__void/*` and HTML document ISR. - The framework Workers pass static files and prerendered pages to `ASSETS` before rendering, so hooks and middleware do not run for them: SvelteKit's adapter Worker, Astro's (`matchStaticAsset`), and Nitro's `cloudflare-module` preset (`isPublicAssetURL`). A missing file still reaches the Worker, which answers as before. ### SvelteKit's asset directory SvelteKit uploads its Worker directory as its assets. With `true`, its Worker answered only its own files, so a module Void left there was stored but not served (#737). Cloudflare now serves any uploaded file from that directory, so `.assetsignore` must list every module Void adds. A comment at that list says so. The test that checks SvelteKit's uploaded files now enables ISR, so it covers `__void_isr.mjs` as well. ### Projects deployed with v0.20 v0.20 wrote `run_worker_first: true` into the root `wrangler.jsonc`, and the migration to `void.config.ts` copied it into `cloudflare.assets`. Those projects keep `true` until they remove that line. ## Tests - `packages/deploy-cloudflare/test/unit/framework.test.ts`: a given `run_worker_first` (a rule list, or `false`) replaces an earlier `true`, and writing it again changes nothing. - `packages/void/test/unit/cloudflare-deploy.test.ts`: - The SvelteKit case expects the new default. - An Astro project whose `void.lock.json` kept an earlier `true` gets the default. - `["/api/*"]`, `true`, and `false` set in `void.config.ts` are written as is. - The SvelteKit asset case enables ISR, so `__void_isr.mjs` must stay out of the upload too. Without this fix, the default, lock, `["/api/*"]`, and `false` cases fail with `run_worker_first: true`. ## Verification - `vp run test` (all 794 files): 793 pass, 1 skipped (16,695 tests pass, 30 skipped). - `vp run check`: 33/33 pass. - Miniflare, with a Worker that stands in for a wrapped framework Worker and marks its responses, and an `/_astro/*` immutable rule in `_headers`: - With `true`, `/_astro/app.abc123.js`, `/`, `/about/`, `/smoke`, and `/__void/ready` all start the Worker. - With the new rule, the file and the two prerendered pages are served without it, with the same status, `Cache-Control`, and body. `/smoke` renders in the Worker, and `/__void/ready` answers `{"ready":true}`. - Not run: `void deploy` against Cloudflare. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent bf20661 commit edef7fd

5 files changed

Lines changed: 129 additions & 5 deletions

File tree

‎docs/guide/edge/static-assets.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,8 @@ Choose `single-page-application`, `404-page`, or `none`. These settings preserve
9191

9292
SvelteKit, Nuxt, Analog, and Astro handle their own error pages and ignore `routing.notFound`. For direct Cloudflare deployment with TanStack Start, React Router, or vinext, configure the asset binding, directory, and routing policy through the framework's Cloudflare config.
9393

94+
With `void deploy --platform cloudflare`, SvelteKit, Nuxt, Analog, and Astro apps serve built files and prerendered pages without starting the Worker, and requests without a matching file reach the framework. To start the Worker first for other paths, set [`run_worker_first`](https://developers.cloudflare.com/workers/static-assets/binding/#run_worker_first) under `cloudflare.assets` in `void.config.ts`. With `true`, every request starts the Worker and counts toward its request usage.
95+
9496
## API routes and SSR pages
9597

9698
API responses and SSR pages are not cached as static assets. Use [Revalidation](./revalidation) to cache public rendered pages.

‎packages/deploy-cloudflare/src/framework.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,12 @@ export type CloudflareFrameworkDeployConfig = Readonly<{
1717
requiredSecrets?: ReadonlyArray<string>;
1818
versionMetadataBinding?: string;
1919
ai?: Readonly<{ binding: string; gateway?: string }>;
20+
/**
21+
* `assets.run_worker_first`. Cloudflare serves a request it does not match
22+
* from the asset directory when a file exists there, without starting the
23+
* Worker. Defaults to `true`, which starts the Worker for every request.
24+
*/
25+
runWorkerFirst?: boolean | ReadonlyArray<string>;
2026
}>;
2127

2228
/**
@@ -54,7 +60,7 @@ export function writeCloudflareFrameworkDeployConfig(
5460
upsert(['no_bundle'], false);
5561
upsert(['assets', 'directory'], options.assetsDirectory);
5662
upsert(['assets', 'binding'], 'ASSETS');
57-
upsert(['assets', 'run_worker_first'], true);
63+
upsert(['assets', 'run_worker_first'], options.runWorkerFirst ?? true);
5864
upsert(['assets', 'not_found_handling'], 'none');
5965
if (options.crons !== undefined) {
6066
upsert(['triggers', 'crons'], [...options.crons]);

‎packages/deploy-cloudflare/test/unit/framework.test.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,36 @@ describe('Cloudflare framework deployment', () => {
9595
);
9696
});
9797

98+
it.each([[['/__void', '/__void/*']], [false]])(
99+
'writes the given run_worker_first over the value an earlier deploy wrote (%j)',
100+
(runWorkerFirst) => {
101+
const root = mkdtempSync(join(tmpdir(), 'void-framework-config-'));
102+
const configPath = join(root, 'wrangler.jsonc');
103+
writeFileSync(
104+
configPath,
105+
JSON.stringify({ assets: { run_worker_first: true, not_found_handling: 'none' } }),
106+
);
107+
const input = {
108+
configPath,
109+
deployPointerPath: join(root, '.wrangler/deploy/config.json'),
110+
name: 'framework-app',
111+
accountId: 'account-id',
112+
main: 'dist/server/entry.mjs',
113+
assetsDirectory: 'dist/client',
114+
compatibilityDate: '2026-09-11',
115+
runWorkerFirst,
116+
};
117+
expect(writeCloudflareFrameworkDeployConfig(input)).toBe(true);
118+
expect(writeCloudflareFrameworkDeployConfig(input)).toBe(false);
119+
expect(parseRootWranglerConfig(configPath).assets).toEqual({
120+
run_worker_first: runWorkerFirst,
121+
not_found_handling: 'none',
122+
directory: 'dist/client',
123+
binding: 'ASSETS',
124+
});
125+
},
126+
);
127+
98128
it('removes stale cron schedules when the current source has none', () => {
99129
const root = mkdtempSync(join(tmpdir(), 'void-framework-config-'));
100130
const configPath = join(root, 'wrangler.jsonc');

‎packages/void/src/cli/deploy-cloudflare-static.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,14 @@ export async function prepareCloudflareFrameworkArtifact(options: {
149149
requiredSecrets: requiredSecretNames,
150150
versionMetadataBinding,
151151
...(ai ? { ai: { ...ai, gateway: voidConfig.ai?.gateway } } : {}),
152+
// Like the framework's own Cloudflare config, let Cloudflare serve built files and
153+
// prerendered pages without starting the Worker. Paths without a file still reach it through
154+
// `not_found_handling: 'none'`; the rule also keeps Void's internal paths on it. Read the
155+
// authored value: the generated config can still hold the `true` an older deploy wrote.
156+
runWorkerFirst: voidConfig.cloudflare?.assets?.run_worker_first ?? [
157+
...VOID_INTERNAL_WORKER_FIRST,
158+
],
159+
// Cloudflare serves any uploaded file without the Worker, so list every module Void adds here.
152160
...(preset.workerDir === preset.assetsDir
153161
? {
154162
assetsIgnore: [

‎packages/void/test/unit/cloudflare-deploy.test.ts‎

Lines changed: 82 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,10 @@ import {
9595
writeWranglerPublishedTrafficSnapshot,
9696
writeProvisionedWranglerConfig,
9797
} from '../../src/cli/wrangler.ts';
98+
import {
99+
materializeCloudflareConfig,
100+
persistCloudflareConfig,
101+
} from '../../src/cloudflare-config.ts';
98102
import { readConfig } from '../../src/config.ts';
99103

100104
// `runDeploy` calls `runCloudflareDeploy` without deps. A test that starts from `runDeploy` sets
@@ -7874,7 +7878,7 @@ describe('runCloudflareDeploy — framework artifact guard', () => {
78747878
assets: {
78757879
directory: '.svelte-kit/cloudflare',
78767880
binding: 'ASSETS',
7877-
run_worker_first: true,
7881+
run_worker_first: ['/__void', '/__void/*'],
78787882
},
78797883
triggers: { crons: ['0 * * * *'] },
78807884
secrets: { required: ['API_TOKEN'] },
@@ -7883,16 +7887,17 @@ describe('runCloudflareDeploy — framework artifact guard', () => {
78837887
expect(readFileSync(join(root, 'wrangler.jsonc'), 'utf-8')).toContain('// keep this comment');
78847888
});
78857889

7886-
// SvelteKit's Worker directory is also its asset directory. In an ES module package, which is
7887-
// what `sv create` makes, Vite names the cron and queue bundle `__void_handlers.js`.
7890+
// SvelteKit's Worker directory is also its asset directory, and Cloudflare serves an uploaded
7891+
// file there without starting the Worker. In an ES module package, which is what `sv create`
7892+
// makes, Vite names the cron and queue bundle `__void_handlers.js`.
78887893
it('keeps the modules it adds to an ES module SvelteKit Worker out of its assets', async () => {
78897894
const root = makeProject({
78907895
'package.json': JSON.stringify({
78917896
name: 'skapp',
78927897
type: 'module',
78937898
dependencies: { '@sveltejs/kit': '2.0.0' },
78947899
}),
7895-
'void.json': JSON.stringify({}),
7900+
'void.json': JSON.stringify({ routing: { revalidate: { '/news/*': 60 } } }),
78967901
'wrangler.jsonc': JSON.stringify({ name: 'skapp', account_id: 'acc123' }),
78977902
'.svelte-kit/cloudflare/_worker.js':
78987903
'export default { fetch() { return new Response("ok") } };\n',
@@ -7916,6 +7921,7 @@ describe('runCloudflareDeploy — framework artifact guard', () => {
79167921

79177922
const directory = join(root, '.svelte-kit/cloudflare');
79187923
expect(existsSync(join(directory, '__void_handlers.js'))).toBe(true);
7924+
expect(existsSync(join(directory, '__void_isr.mjs'))).toBe(true);
79197925
const ignored = ignore().add(readFileSync(join(directory, '.assetsignore'), 'utf-8'));
79207926
const assets = readdirSync(directory, { recursive: true, encoding: 'utf8' })
79217927
.map((file) => toSlash(file))
@@ -7924,6 +7930,78 @@ describe('runCloudflareDeploy — framework artifact guard', () => {
79247930
expect(assets).toEqual(['_app/immutable/app.js']);
79257931
});
79267932

7933+
// Astro's own Cloudflare config starts the Worker only for paths without a file. An older Void
7934+
// deploy wrote `run_worker_first: true` into the generated config, which void.lock.json can keep.
7935+
it('replaces the run_worker_first an older framework deploy recorded', async () => {
7936+
const preset = FRAMEWORK_PRESETS.astro!;
7937+
const root = makeProject({
7938+
'void.config.ts': `export default { cloudflare: { name: 'astro-app', account_id: 'acc123' } };\n`,
7939+
[`${preset.workerDir}/${preset.workerMain}`]:
7940+
'export default { fetch() { return new Response("page") } };\n',
7941+
[`${preset.assetsDir}/_astro/app.js`]: 'console.log("client");\n',
7942+
});
7943+
const configPath = materializeCloudflareConfig(root);
7944+
writeFileSync(
7945+
configPath,
7946+
JSON.stringify({
7947+
...parseRootWranglerConfig(configPath),
7948+
assets: { run_worker_first: true },
7949+
}),
7950+
);
7951+
persistCloudflareConfig(root);
7952+
expect(parseRootWranglerConfig(materializeCloudflareConfig(root)).assets).toEqual({
7953+
run_worker_first: true,
7954+
});
7955+
7956+
await prepareCloudflareFrameworkArtifact({
7957+
root,
7958+
configPath,
7959+
accountId: 'acc123',
7960+
workerName: 'astro-app',
7961+
voidConfig: readConfig(root),
7962+
framework: { name: 'astro', class: 'c' },
7963+
preset,
7964+
});
7965+
7966+
expect(parseRootWranglerConfig(configPath).assets).toMatchObject({
7967+
run_worker_first: ['/__void', '/__void/*'],
7968+
not_found_handling: 'none',
7969+
});
7970+
});
7971+
7972+
it.each([[['/api/*']], [true], [false]])(
7973+
'writes the run_worker_first that void.config.ts sets for a framework Worker (%j)',
7974+
async (runWorkerFirst) => {
7975+
const preset = FRAMEWORK_PRESETS.astro!;
7976+
const cloudflare = {
7977+
name: 'astro-app',
7978+
account_id: 'acc123',
7979+
assets: { run_worker_first: runWorkerFirst },
7980+
};
7981+
const root = makeProject({
7982+
'void.config.ts': `export default { cloudflare: ${JSON.stringify(cloudflare)} };\n`,
7983+
[`${preset.workerDir}/${preset.workerMain}`]:
7984+
'export default { fetch() { return new Response("page") } };\n',
7985+
[`${preset.assetsDir}/_astro/app.js`]: 'console.log("client");\n',
7986+
});
7987+
const configPath = materializeCloudflareConfig(root);
7988+
7989+
await prepareCloudflareFrameworkArtifact({
7990+
root,
7991+
configPath,
7992+
accountId: 'acc123',
7993+
workerName: 'astro-app',
7994+
voidConfig: readConfig(root),
7995+
framework: { name: 'astro', class: 'c' },
7996+
preset,
7997+
});
7998+
7999+
expect(parseRootWranglerConfig(configPath).assets).toMatchObject({
8000+
run_worker_first: runWorkerFirst,
8001+
});
8002+
},
8003+
);
8004+
79278005
it('prepares Class A wrapper handlers without replacing its generated config pointer', async () => {
79288006
const root = makeProject({
79298007
'package.json': JSON.stringify({

0 commit comments

Comments
 (0)