Skip to content

Commit 8e41c4e

Browse files
morinokamiclaude
andcommitted
Report queue options and page settings that Void cannot read.
Void reads these values from the source without running it, and used to skip every form other than `export const name = <literal>` silently. - Queue options exported in another form (re-exports, export lists, let, destructuring) now fail the build instead of deploying Cloudflare's defaults. - Page revalidate, prerender, ssr and layout values that cannot be read are still ignored, but now print a warning. A hard error would break builds that already ship them. - `export * from` in a queue file, page server file or page component prints a warning, including when a comment sits between the tokens. - Svelte instance-script exports are component props, so they are not treated as layout settings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 7dd56a7 commit 8e41c4e

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)