Skip to content

Commit 73dbf57

Browse files
morinokamiclaude
andauthored
fix: report queue options and page settings that Void cannot read (#754)
Void reads queue consumer options from the source without running it, and only understands `export const name = <literal>`. Every other way of exporting the same name is skipped without a message. A queue that shares its options through a module builds and deploys with Cloudflare's defaults: ```ts // queues/_options.ts export const maxRetries = 0; export const retryDelay = 30; ``` ```ts // queues/emails.ts import { defineQueue } from 'void'; export { maxRetries, retryDelay } from './_options'; export default defineQueue(async (batch) => { // ... }); ``` The consumer gets `maxRetries` 3 and `retryDelay` 0, so a failing message is retried three times without delay instead of being dropped. The same happens with export lists (`export { maxRetries }`), `let` and `var`, destructuring, and `export * from`. The queues guide only says "Export named constants". Page settings are read the same way: `revalidate`, `prerender` and `ssr` in a page's `.server.ts`, and `layout` in a page component. There, a computed value is skipped as well: with `export const revalidate = 60 * 60`, the page falls back to `routing.revalidate`. ## Fix The shared reader in `shared/static-exports.ts` now also reports the names a scanner asks about that are exported in a form whose value it cannot read, and whether the module uses `export * from`. Each scanner decides what to do with them: - Queue options in another form fail the build, as computed values already did: ``` queue: maxRetries in 'emails.ts' must be declared in the queue file as `export const maxRetries = <integer>`. Re-exported options and other export forms are not read. ``` - Page settings that cannot be read are still ignored, but print a warning once per file. A hard error would break builds that ship them today, which is also why #433 made layout paths a warning. - `export * from` in a queue file, a page's `.server.ts` or a page component prints a warning, since Void cannot tell which names it brings in. The check that decides whether to parse a file skips whitespace and comments, so `export /* shared */ * from` counts too. A queue file that declares all four options, or a page that declares its own layout, gets no warning: its own exports take precedence. - In a `.server.ts`, that warning also names `loader`, `action`, `actions` and `getPrerenderPaths`. Page method detection doesn't follow `export *` either, which affects automatic prerendering, action types and the prerender path list. - Exports in a Svelte instance script declare component props, so `export let layout` there is not read as a layout setting and gets no warning. A layout in a later `<script module>` is still found. Type-only exports are ignored. Values written as `export const name = <literal>` are read as before. The cron scanner moves to the new reader without a change in behavior. The queues, revalidation, Pages overview and layouts guides now say that these values must be literals declared with `export const` in the file itself. **Behavior change:** an app that shares queue options through another module now fails to build until each queue file declares them. Those values were never applied. ## Tests - `packages/void/test/unit/queue-scan.test.ts`: re-exports, export lists, a renamed local, `let` and destructuring fail with the message above. `export * from` warns once, also with a comment or line breaks between `export` and `*`. Type-only exports, and a file that declares all four options beside `export *`, stay silent. - `packages/void/test/unit/pages-scan.test.ts`: a computed `revalidate`, non-boolean `prerender` and `ssr`, re-exported, renamed, `let` and destructured settings, unreadable and non-string layouts, and `export *` in server files and components each warn once and keep the default. Type-only exports and a layout declared beside `export *` stay silent. A Svelte `<script module>` or `<script context="module">` layout after an instance prop named `layout` is read, and an instance prop alone gets no warning. Each of the 21 new error and warning cases fails without this fix. ## Verification - `vp test run`: 785 files pass, 1 skipped (16,406 tests pass, 30 skipped). - `vp run check`: 33/33 pass. - The React, Vue, Svelte and Solid Pages playgrounds build without new warnings. - 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 655a0d9 commit 73dbf57

12 files changed

Lines changed: 580 additions & 60 deletions

File tree

‎docs/guide/edge/revalidation.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ export const loader = defineHandler(async (c) => {
6161
});
6262
```
6363

64+
Use a whole-number literal such as `3600`. Void reads the value without running the file, so it ignores an expression such as `60 * 60` or a value re-exported from another module, and prints a warning.
65+
6466
Per-page values take precedence over `void.config.ts` patterns.
6567

6668
A page's `revalidate` export also applies to `routes/` handlers whose URLs match the page pattern. For example, if `pages/[...slug].server.ts` exports `revalidate`, Void can also cache the `GET` response of `routes/now.ts`. Void never caches paths under `/api`. To keep a route handler's response out of the cache, set `x-revalidate: 0` on it. See [Per-response TTL override](#per-response-ttl-override).

‎docs/guide/pages-routing/layouts.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,8 @@ A named layout replaces the deepest default layout: in `[root, docs/layout]`, it
216216

217217
Void uses the closest matching `_layouts/` file in the page's directory or an ancestor. A missing named layout fails the build.
218218

219+
Declare `layout` in the page file itself with a string literal or `false`. Void reads it without running the page, so it ignores a computed or re-exported value and prints a warning.
220+
219221
## Shared Data
220222

221223
Middleware can inject data available on every page via `c.set("shared", {...})`. Augment `CloudContextVariables` to type the shared data, and `useShared()` will infer the type automatically:

‎docs/guide/pages-routing/overview.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,8 @@ Render and prerender flags combine like this:
153153
| Island page + `ssr = false` | Invalid. Island pages already use the island renderer. |
154154
| `output: "static"` + `prerender` unset | Auto-prerender pages that have known paths, including client-only shells. |
155155

156+
Write `ssr` and `prerender` as `true` or `false` with `export const` in the `.server.ts` file itself. Void reads them without running the file, so it ignores a computed or re-exported value and prints a warning.
157+
156158
### Typed navigation
157159

158160
Use the `Link` component for SPA navigation between pages. Build dynamic URLs with [`routeUrl()`](../type-safety.md#typed-urls-and-navigation) to check the route pattern and its parameters:

‎docs/guide/queues.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,8 @@ export default defineQueue<Message>(async (batch, env) => {
110110
- `maxRetries`: maximum number of retries before delivery is exhausted (default `3`)
111111
- `retryDelay`: seconds to wait between retries (default `0`)
112112

113+
Declare each option in the queue file with `export const` and a whole-number literal. Void reads these values without running the file, so computed values and options re-exported from another module are not supported. To use the same value in several queues, repeat it in each queue file.
114+
113115
Void-managed queues do not configure a dead-letter queue. Cloudflare permanently
114116
deletes messages that exhaust their retries without one; see
115117
[Cloudflare's dead-letter queue guide](https://developers.cloudflare.com/queues/configuration/dead-letter-queues/).

‎packages/void/src/crons/scan.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import { join } from 'pathslash';
33
import type { AstNode } from '../shared/ast.ts';
44
import { listConventionFiles } from '../shared/convention-files.ts';
55
import {
6-
staticExportInitializers,
6+
readStaticExports,
77
staticLiteral,
88
unwrapStaticExpression,
99
} from '../shared/static-exports.ts';
@@ -23,7 +23,7 @@ function extractJobName(filePath: string): string {
2323

2424
function extractCronExpressions(source: string, filePath: string): Array<string> {
2525
const initializer = unwrapStaticExpression(
26-
staticExportInitializers(filePath, source, new Set(['cron'])).get('cron'),
26+
readStaticExports(filePath, source, new Set(['cron'])).initializers.get('cron'),
2727
);
2828
if (!initializer) {
2929
throw new Error(

‎packages/void/src/pages/island-imports.ts‎

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,30 @@ export type IslandSourceEdit = { start: number; end: number; text: string };
1515

1616
export type StaticCssImport = { statement: string; specifier: string };
1717

18-
type ScriptBlock = { source: string; offset: number; filename: string };
18+
type ScriptBlock = {
19+
source: string;
20+
offset: number;
21+
filename: string;
22+
/** A Svelte instance script: its exports declare component props, not module exports. */
23+
instance?: boolean;
24+
};
25+
26+
const SCRIPT_ATTRIBUTE_RE = /([^\s"'=/]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
27+
28+
/** `<script module>` (Svelte 5) or `<script context="module">` (Svelte 4). */
29+
function isSvelteModuleScript(attributes: string): boolean {
30+
for (const [, name, doubleQuoted, singleQuoted, bare] of attributes.matchAll(
31+
SCRIPT_ATTRIBUTE_RE,
32+
)) {
33+
if (
34+
name === 'module' ||
35+
(name === 'context' && (doubleQuoted ?? singleQuoted ?? bare) === 'module')
36+
) {
37+
return true;
38+
}
39+
}
40+
return false;
41+
}
1942

2043
// Same leading-script rule as @void/md's extractScript: a markdown page may open
2144
// with a <script> block, and its frontmatter starts right after that block.
@@ -40,9 +63,18 @@ export function scriptBlocks(code: string, filename: string): Array<ScriptBlock>
4063
return [{ source: code, offset: 0, filename }];
4164
}
4265
const scriptFilename = filename.replace(/\.(?:vue|svelte)$/, '.ts');
43-
return [...code.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script\s*>/gi)].map((match) => {
44-
const source = match[1]!;
45-
return { source, offset: match.index! + match[0].indexOf(source), filename: scriptFilename };
66+
const svelte = filename.endsWith('.svelte');
67+
return [...code.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi)].map((match) => {
68+
const source = match[2]!;
69+
const block: ScriptBlock = {
70+
source,
71+
offset: match.index! + match[0].indexOf(source),
72+
filename: scriptFilename,
73+
};
74+
if (svelte && !isSvelteModuleScript(match[1]!)) {
75+
block.instance = true;
76+
}
77+
return block;
4678
});
4779
}
4880

‎packages/void/src/pages/scan.ts‎

Lines changed: 125 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,12 @@ import {
2424
} from '../shared/ast.ts';
2525
import { ROUTE_EXTENSIONS, ROUTE_EXTENSIONS_SET } from '../shared/route-extensions.ts';
2626
import { deriveFromSource } from '../shared/source-analysis-cache.ts';
27-
import { staticExportInitializers, staticLiteral } from '../shared/static-exports.ts';
27+
import {
28+
mayExportAll,
29+
readStaticExports,
30+
staticExports,
31+
staticLiteral,
32+
} from '../shared/static-exports.ts';
2833
import { MARKDOWN_SCRIPT_RE, scriptBlocks } from './island-imports.ts';
2934
import { resolveNamedLayout } from './layout-resolution.ts';
3035
import { patternToRegex } from './manifest.ts';
@@ -47,6 +52,23 @@ export const MAX_REVALIDATE = 31536000; // 1 year in seconds
4752
const warnedLayoutPaths = new Set<string>();
4853
/** Unreachable pages already reported, for the same reason. */
4954
const warnedShadowedPages = new Set<string>();
55+
/** Ignored page settings already reported, for the same reason. */
56+
const warnedPageSettings = new Set<string>();
57+
58+
/**
59+
* Page settings (layout, revalidate, prerender, ssr) are read from the source
60+
* without running it. One the source does not show keeps its default, as
61+
* before, with a warning: a hard error would break builds that already ship it.
62+
*/
63+
function warnPageSettings(pagesDir: string, warnings: ReadonlyArray<string>): void {
64+
for (const warning of warnings) {
65+
const key = `${pagesDir}\0${warning}`;
66+
if (!warnedPageSettings.has(key)) {
67+
warnedPageSettings.add(key);
68+
voidWarn(warning);
69+
}
70+
}
71+
}
5072

5173
type PageRenderingSource = {
5274
componentPath: string;
@@ -83,27 +105,62 @@ type PageServerMetadata = {
83105
prerender?: ExplicitBoolean;
84106
ssr?: ExplicitBoolean;
85107
hasGetPrerenderPaths?: boolean;
108+
/** Settings the scan ignores, reported once by scanPages. */
109+
warnings: Array<string>;
86110
};
87111

88-
function componentLayout(source: string, filename: string): string | false | undefined {
89-
if (!source.includes('layout')) {
90-
return undefined;
112+
type ComponentLayout = {
113+
layout: string | false | undefined;
114+
/** Layout exports the scan ignores, reported once by scanPages. */
115+
warnings: Array<string>;
116+
};
117+
118+
const LAYOUT_EXPORT: ReadonlySet<string> = new Set(['layout']);
119+
120+
function mayExportLayout(source: string): boolean {
121+
return source.includes('layout') || mayExportAll(source);
122+
}
123+
124+
/** The first script block that declares a readable layout wins; warnings only apply when none does. */
125+
function componentLayout(source: string, filename: string): ComponentLayout {
126+
if (!mayExportLayout(source)) {
127+
return { layout: undefined, warnings: [] };
91128
}
129+
let ignored: string | undefined;
130+
let exportsAll = false;
92131
for (const script of scriptBlocks(source, filename)) {
93-
if (!script.source.includes('layout')) {
132+
if (!mayExportLayout(script.source)) {
94133
continue;
95134
}
96-
const initializer = staticExportInitializers(
97-
script.filename,
98-
script.source,
99-
new Set(['layout']),
100-
).get('layout');
135+
const exports = readStaticExports(script.filename, script.source, LAYOUT_EXPORT);
136+
const initializer = exports.initializers.get('layout');
101137
const value = staticLiteral(initializer);
102138
if (typeof value === 'string' || value === false) {
103-
return value;
139+
return { layout: value, warnings: [] };
104140
}
141+
// `export let layout` in a Svelte instance script declares a prop of that name.
142+
if (script.instance) {
143+
continue;
144+
}
145+
exportsAll ||= exports.exportsAll;
146+
if (exports.unreadable.has('layout')) {
147+
ignored ??= `pages: layout in '${filename}' is ignored. Declare it in that file as \`export const layout = '<name>'\`; re-exported layouts and other export forms are not read.`;
148+
} else if (initializer) {
149+
ignored ??= `pages: layout in '${filename}' is ignored. It must be a string literal or \`false\`, such as \`export const layout = 'landing'\`.`;
150+
}
151+
}
152+
if (ignored) {
153+
return { layout: undefined, warnings: [ignored] };
154+
}
155+
if (exportsAll) {
156+
return {
157+
layout: undefined,
158+
warnings: [
159+
`pages: '${filename}' uses \`export * from\`. Void does not read a layout export through it, so declare layout in that file with \`export const\`.`,
160+
],
161+
};
105162
}
106-
return undefined;
163+
return { layout: undefined, warnings: [] };
107164
}
108165

109166
const TRANSPARENT_EXPRESSION_TYPES = new Set([
@@ -121,8 +178,58 @@ function readLiteral(node: AstNode | null | undefined): unknown {
121178
return isLiteral(node) ? node.value : undefined;
122179
}
123180

181+
const PAGE_SETTINGS = ['revalidate', 'prerender', 'ssr'] as const;
182+
const PAGE_SETTING_SET: ReadonlySet<string> = new Set(PAGE_SETTINGS);
183+
const PAGE_SETTING_PLACEHOLDERS = {
184+
revalidate: '<seconds>',
185+
prerender: '<boolean>',
186+
ssr: '<boolean>',
187+
} as const;
188+
189+
/** Read revalidate, prerender and ssr from a page's server file, collecting warnings for values it cannot read. */
190+
function readPageSettings(
191+
program: AstProgram,
192+
filename: string,
193+
metadata: PageServerMetadata,
194+
): void {
195+
const settings = staticExports(program, PAGE_SETTING_SET);
196+
for (const name of PAGE_SETTINGS) {
197+
if (settings.unreadable.has(name)) {
198+
metadata.warnings.push(
199+
`pages: ${name} in '${filename}' is ignored. Declare it in that file as \`export const ${name} = ${PAGE_SETTING_PLACEHOLDERS[name]}\`; re-exported settings and other export forms are not read.`,
200+
);
201+
continue;
202+
}
203+
const initializer = settings.initializers.get(name);
204+
if (!initializer) {
205+
continue;
206+
}
207+
const value = readLiteral(initializer);
208+
if (name === 'revalidate') {
209+
if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
210+
metadata.revalidate = value;
211+
} else {
212+
metadata.warnings.push(
213+
`pages: revalidate in '${filename}' is ignored. It must be a nonnegative integer literal, such as \`export const revalidate = 3600\`.`,
214+
);
215+
}
216+
} else if (typeof value === 'boolean') {
217+
metadata[name] = value;
218+
} else {
219+
metadata.warnings.push(
220+
`pages: ${name} in '${filename}' is ignored. It must be \`true\` or \`false\`.`,
221+
);
222+
}
223+
}
224+
if (settings.exportsAll) {
225+
metadata.warnings.push(
226+
`pages: '${filename}' uses \`export * from\`. Void does not see page exports through it, so export loader, action, actions and getPrerenderPaths by name, and declare revalidate, prerender and ssr in that file with \`export const\`.`,
227+
);
228+
}
229+
}
230+
124231
function detectPageServerMetadata(source: string, filename: string): PageServerMetadata {
125-
const metadata: PageServerMetadata = { methods: [] };
232+
const metadata: PageServerMetadata = { methods: [], warnings: [] };
126233
let parsed: ReturnType<typeof parseSync>;
127234
try {
128235
parsed = parseSync(filename, source);
@@ -150,20 +257,6 @@ function detectPageServerMetadata(source: string, filename: string): PageServerM
150257
metadata.hasGetPrerenderPaths = true;
151258
}
152259
}
153-
if (isIdentifier(variable.id) && variables.kind === 'const') {
154-
const name = variable.id.name;
155-
if (name === 'revalidate') {
156-
const value = readLiteral(variable.init);
157-
if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
158-
metadata.revalidate = value;
159-
}
160-
} else if (name === 'prerender' || name === 'ssr') {
161-
const value = readLiteral(variable.init);
162-
if (typeof value === 'boolean') {
163-
metadata[name] = value;
164-
}
165-
}
166-
}
167260
}
168261
} else if (declaration?.type === 'FunctionDeclaration') {
169262
const functionName = (declaration as AstFunctionDeclaration).id;
@@ -187,6 +280,7 @@ function detectPageServerMetadata(source: string, filename: string): PageServerM
187280
}
188281
}
189282
}
283+
readPageSettings(program, filename, metadata);
190284
return metadata;
191285
}
192286

@@ -351,6 +445,7 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis
351445
prerender = metadata.prerender;
352446
ssr = metadata.ssr;
353447
hasGetPrerenderPaths = metadata.hasGetPrerenderPaths;
448+
warnPageSettings(pagesDir, metadata.warnings);
354449
break;
355450
}
356451
}
@@ -386,9 +481,11 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis
386481
layout: extractFrontmatterLayout(source, matter),
387482
})));
388483
} else {
389-
layout = deriveFromSource(join(pagesDir, file), 'page-layout', (source) =>
484+
const component = deriveFromSource(join(pagesDir, file), 'page-layout', (source) =>
390485
componentLayout(source, file),
391486
);
487+
layout = component.layout;
488+
warnPageSettings(pagesDir, component.warnings);
392489
}
393490

394491
pages.push({

‎packages/void/src/queues/scan.ts‎

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
import { readFileSync } from 'node:fs';
22
import { join } from 'pathslash';
3+
import { voidWarn } from '../log.ts';
4+
import type { AstNode } from '../shared/ast.ts';
35
import { listConventionFiles } from '../shared/convention-files.ts';
4-
import { staticExportInitializers, staticLiteral } from '../shared/static-exports.ts';
6+
import { mayExportAll, readStaticExports, staticLiteral } from '../shared/static-exports.ts';
57

68
export type QueueDefinition = {
79
/** Relative file path from queues/ */
@@ -29,6 +31,43 @@ function deriveQueueBindingName(name: string): string {
2931
}
3032

3133
const OPTION_NAMES = ['maxBatchSize', 'maxBatchTimeout', 'maxRetries', 'retryDelay'] as const;
34+
const OPTION_NAME_SET: ReadonlySet<string> = new Set(OPTION_NAMES);
35+
36+
/** Queue files already warned about `export *`; a dev server rescans queues on every change. */
37+
const warnedExportAll = new Set<string>();
38+
39+
/**
40+
* Consumer options configure Cloudflare before any queue code runs, so they are
41+
* read from the source. Reject exports whose value the source does not show,
42+
* instead of deploying Cloudflare's defaults.
43+
*/
44+
function readOptionInitializers(
45+
absPath: string,
46+
filePath: string,
47+
source: string,
48+
): Map<string, AstNode> {
49+
if (!OPTION_NAMES.some((option) => source.includes(option)) && !mayExportAll(source)) {
50+
return new Map();
51+
}
52+
const exports = readStaticExports(absPath, source, OPTION_NAME_SET);
53+
const unreadable = OPTION_NAMES.find((option) => exports.unreadable.has(option));
54+
if (unreadable) {
55+
throw new Error(
56+
`queue: ${unreadable} in '${filePath}' must be declared in the queue file as \`export const ${unreadable} = <integer>\`. Re-exported options and other export forms are not read.`,
57+
);
58+
}
59+
if (
60+
exports.exportsAll &&
61+
OPTION_NAMES.some((option) => !exports.initializers.has(option)) &&
62+
!warnedExportAll.has(absPath)
63+
) {
64+
warnedExportAll.add(absPath);
65+
voidWarn(
66+
`queue: '${filePath}' uses \`export * from\`. Void does not read consumer options through it, so declare them in the queue file with \`export const\`. Re-export other names individually to remove this warning.`,
67+
);
68+
}
69+
return exports.initializers;
70+
}
3271

3372
export function scanQueuesSync(queuesDir: string): Array<QueueDefinition> {
3473
const definitions = listConventionFiles(queuesDir)
@@ -37,9 +76,7 @@ export function scanQueuesSync(queuesDir: string): Array<QueueDefinition> {
3776
const absPath = join(queuesDir, filePath);
3877
const source = readFileSync(absPath, 'utf-8');
3978
const name = extractName(filePath);
40-
const options = OPTION_NAMES.some((option) => source.includes(option))
41-
? staticExportInitializers(absPath, source, new Set(OPTION_NAMES))
42-
: new Map();
79+
const options = readOptionInitializers(absPath, filePath, source);
4380
const optionValue = (option: (typeof OPTION_NAMES)[number]): number | undefined => {
4481
const initializer = options.get(option);
4582
if (!initializer) {

0 commit comments

Comments
 (0)