@pajecawav/yamf 0.0.8 → 0.0.9

package/src/page.tsx

@@ -1,13 +1,14 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { Fragment, type Child } from "hono/jsx";
 import { renderToReadableStream } from "hono/jsx/streaming";
 import { Hono } from "hono/tiny";
 import type { EventHandlerResponse, H3Event } from "nitro/h3";
-import { HTTPResponse, withServerTiming } from "nitro/h3";
+import { HTTPError, HTTPResponse, withServerTiming } from "nitro/h3";
 import { useSeoMeta } from "unhead";
 import type { Unhead } from "unhead/server";
 import { transformHtmlTemplate } from "unhead/server";
-import { createStreamableHead, wrapStream } from "unhead/stream/server";
-import type { ResolvableLink, UseSeoMetaInput } from "unhead/types";
+import { createStreamableHead, renderSSRHeadSuspenseChunk, wrapStream } from "unhead/stream/server";
+import type { ResolvableHead, ResolvableLink, UseSeoMetaInput } from "unhead/types";
 import { Root as RootComponent } from "virtual:yamf:root";
 import { template } from "virtual:yamf:template";
 import { Router } from "wouter";
@@ -20,24 +21,160 @@ export type PageHandler = (
 	params: {
 		assets: ImportAssetsResult;
 		head?: YamfHead;
+		nonce?: string;
 	},
 ) => EventHandlerResponse;
 
-export type PageRenderer = (
+export type PageRenderer<P = unknown, Q = unknown> = (
 	event: H3Event,
 	params: {
 		head: Unhead;
 		seoHead: (input: UseSeoMetaInput) => void;
+		params: P;
+		query: Q;
 	},
 ) => HTTPResponse | Child | Promise<Child | HTTPResponse>;
 
-interface DefinePageOptions {
-	render: PageRenderer;
+export interface PageCacheOptions {
+	maxAge: number;
+	swr?: number;
+	private?: boolean;
+}
+
+interface DefinePageOptions<P = unknown, Q = unknown> {
+	render: PageRenderer<P, Q>;
 	stream?: boolean;
+	/**
+	 * Cache-Control for the page response. `60` is shorthand for
+	 * `{ maxAge: 60 }` → `Cache-Control: public, max-age=60`; the object form
+	 * adds `stale-while-revalidate` and `private`.
+	 */
+	cache?: number | PageCacheOptions;
+	/**
+	 * Standard-schema validator (zod, valibot, arktype, …) for the route
+	 * params. On failure the page throws HTTPError 404 before render; the
+	 * validated, typed output is passed to render as `params`.
+	 */
+	params?: StandardSchemaV1<unknown, P>;
+	/**
+	 * Standard-schema validator for the search params. On failure the page
+	 * throws HTTPError 400 before render; the validated, typed output is
+	 * passed to render as `query`. Repeated keys collapse to the last value.
+	 */
+	query?: StandardSchemaV1<unknown, Q>;
 }
 
-export const definePage = (options: DefinePageOptions): PageHandler => {
-	return async (event, { assets, head: headInit }) => {
+const cacheControlValue = (cache: number | PageCacheOptions): string => {
+	const options = typeof cache === "number" ? { maxAge: cache } : cache;
+
+	const parts = [options.private ? "private" : "public", `max-age=${options.maxAge}`];
+
+	if (options.swr !== undefined) {
+		parts.push(`stale-while-revalidate=${options.swr}`);
+	}
+
+	return parts.join(", ");
+};
+
+// resolvable head inputs may be functions — resolve them for serialization
+const unwrapEntryInput = (input: unknown): ResolvableHead => {
+	return (
+		typeof input === "function" ? (input as () => ResolvableHead)() : input
+	) as ResolvableHead;
+};
+
+const collectHeadInputs = (head: Unhead): ResolvableHead[] => {
+	const inputs: ResolvableHead[] = [];
+
+	for (const entry of head.entries.values()) {
+		inputs.push(unwrapEntryInput(entry.input));
+	}
+
+	return inputs;
+};
+
+const serializeHeadPayload = (inputs: ResolvableHead[]): string => {
+	return JSON.stringify(inputs)
+		.replace(/</g, "\\u003c")
+		.replace(/>/g, "\\u003e")
+		.replace(/&/g, "\\u0026");
+};
+
+const scriptNonceAttr = (nonce?: string): string => {
+	return nonce ? ` nonce="${nonce.replace(/"/g, "&quot;")}"` : "";
+};
+
+// client handshake: re-register the server head entries (titleTemplate,
+// htmlAttrs, page-level head) into the client head via the unhead stream
+// queue, so post-hydration updates keep templates and adopt SSR tags
+// instead of duplicating them
+const headPayloadScript = (inputs: ResolvableHead[], nonce?: string): string => {
+	if (!inputs.length) {
+		return "";
+	}
+
+	return `<script${scriptNonceAttr(nonce)}>window.__unhead__&&window.__unhead__.push(${serializeHeadPayload(inputs)})</script>`;
+};
+
+// injected at the start of <body>: unhead rebuilds the html/head tags and
+// appends its head tags (including the stream bootstrap shim) inside <head>,
+// so the payload must come after them for window.__unhead__ to exist
+const injectHeadPayload = (template: string, script: string): string => {
+	if (!script) {
+		return template;
+	}
+
+	if (/<body[^>]*>/.test(template)) {
+		return template.replace(/<body[^>]*>/, match => `${match}${script}`);
+	}
+
+	return template.replace("</head>", `</head>${script}`);
+};
+
+const validateWithSchema = async <T,>(
+	schema: StandardSchemaV1<unknown, T> | undefined,
+	value: unknown,
+	status: 400 | 404,
+	what: string,
+): Promise<T> => {
+	if (!schema) {
+		return value as T;
+	}
+
+	const result = await schema["~standard"].validate(value);
+
+	if (result.issues) {
+		throw new HTTPError(`Invalid ${what}`, {
+			status,
+			cause: new Error(result.issues.map(issue => issue.message).join("; ")),
+		});
+	}
+
+	return result.value;
+};
+
+export const definePage = <P = unknown, Q = unknown>(
+	options: DefinePageOptions<P, Q>,
+): PageHandler => {
+	return async (event, { assets, head: headInit, nonce }) => {
+		if (options.cache !== undefined) {
+			event.res.headers.set("cache-control", cacheControlValue(options.cache));
+		}
+
+		const params = await validateWithSchema(
+			options.params,
+			event.context.params,
+			404,
+			"path params",
+		);
+
+		const query = await validateWithSchema(
+			options.query,
+			Object.fromEntries(event.url.searchParams),
+			400,
+			"query params",
+		);
+
 		const { head } = createStreamableHead({ init: [headInit] });
 		const seoHead = (input?: UseSeoMetaInput) => useSeoMeta(head, input);
 		seoHead(headInit?.seo);
@@ -50,12 +187,17 @@ export const definePage = (options: DefinePageOptions): PageHandler => {
 			script: [{ type: "module", src: assets.entry }],
 		});
 
-		const content = await options.render(event, { head, seoHead });
+		const content = await options.render(event, { head, seoHead, params, query });
 
 		if (content instanceof HTTPResponse) {
 			return content;
 		}
 
+		// must be collected before wrapStream — it clears entries after the shell
+		const payloadScript = headPayloadScript(collectHeadInputs(head), nonce);
+
+		const templateWithPayload = injectHeadPayload(template, payloadScript);
+
 		const Root = RootComponent ?? Fragment;
 
 		const App = async () => (
@@ -83,7 +225,7 @@ export const definePage = (options: DefinePageOptions): PageHandler => {
 
 						html = transformHtmlTemplate(
 							head,
-							template.replace("<!--ssr-outlet-->", html ?? ""),
+							templateWithPayload.replace("<!--ssr-outlet-->", html ?? ""),
 						);
 
 						return new Response(html, responseInit);
@@ -92,7 +234,30 @@ export const definePage = (options: DefinePageOptions): PageHandler => {
 				.request("/");
 		}
 
-		const stream = wrapStream(head, renderToReadableStream(<App />), template);
+		const stream = wrapStream(
+			head,
+			renderToReadableStream(<App />),
+			templateWithPayload,
+			undefined,
+			{
+				// same as unhead's default flushChunk, but with CSP nonce support
+				flushChunk: () => {
+					let chunk: string;
+
+					try {
+						chunk = renderSSRHeadSuspenseChunk(head);
+					} catch {
+						return "";
+					}
+
+					if (!chunk) {
+						return "";
+					}
+
+					return `<script${scriptNonceAttr(nonce)}>window.__unhead__&&(${chunk});document.currentScript.remove()</script>`;
+				},
+			},
+		);
 
 		return new Response(stream, responseInit);
 	};

package/src/safeAsync.tsx

@@ -0,0 +1,46 @@
+import type { Child, FC } from "hono/jsx";
+
+export interface SafeAsyncFallbackProps {
+	error: unknown;
+}
+
+const DefaultFallback: FC<SafeAsyncFallbackProps> = () => (
+	<div
+		role="alert"
+		data-testid="yamf-error"
+		style="padding: 1rem; border: 1px solid currentColor"
+	>
+		Something went wrong.
+	</div>
+);
+
+/**
+ * Wraps an async server component with error handling for streaming SSR.
+ *
+ * When an async component inside a Suspense boundary rejects after the shell
+ * has been flushed, the streaming renderer swallows the error: the browser
+ * keeps the loading fallback forever with a 200 status, and nothing reaches
+ * the error handler. `safeAsync` awaits the component directly, so a
+ * rejection is caught here and rendered as `fallback` instead.
+ *
+ * Catches errors of the wrapped component itself, not of its subtree.
+ */
+export const safeAsync = <P extends object>(
+	Component: (props: P) => Child | Promise<Child>,
+	fallback: FC<SafeAsyncFallbackProps> = DefaultFallback,
+): FC<P> => {
+	const Safe = async (props: P): Promise<Child> => {
+		try {
+			return await Component(props);
+		} catch (error) {
+			console.error("[yamf] safeAsync: async component rejected", error);
+
+			return fallback({ error });
+		}
+	};
+
+	// hono's FC type does not include Promise<Child> in its return type,
+	// but the JSX renderer awaits component results
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion
+	return Safe as FC<P>;
+};

package/src/server/entry.tsx

@@ -24,6 +24,8 @@ interface Route {
 
 const router = createRouter<Route>();
 
+const registeredRoutes = new Map<string, string>();
+
 for (const [relativePath, handler] of Object.entries(pages).toSorted((a, b) =>
 	a[0].localeCompare(b[0]),
 )) {
@@ -46,6 +48,16 @@ for (const [relativePath, handler] of Object.entries(pages).toSorted((a, b) =>
 
 	route = withLeadingSlash(withoutTrailingSlash(route));
 
+	const conflictingFile = registeredRoutes.get(route);
+
+	if (conflictingFile && conflictingFile !== relativePath) {
+		console.warn(
+			`[yamf] duplicate page route "${route}": ${conflictingFile} and ${relativePath} both map to it — the routes conflict`,
+		);
+	}
+
+	registeredRoutes.set(route, relativePath);
+
 	addRoute(router, "GET", route, {
 		handler,
 		serverAssets: pagesServerAssets[relativePath],
@@ -57,6 +69,15 @@ export type ServerEntry = EventHandlerWithFetch<EventHandlerRequest, Promise<unk
 export interface DefineServerEntryOptions {
 	head?: YamfHead | ((event: H3Event) => YamfHead);
 	disableEarlyHints?: boolean;
+	/**
+	 * CSP nonce for the inline scripts yamf injects (head handshake payload
+	 * and streamed head patches).
+	 *
+	 * Note: unhead's stream bootstrap script (`window.__unhead__||(…)`) does
+	 * not support a nonce in unhead 3.x — with a strict `script-src` CSP it
+	 * must be allowed separately (e.g. via a hash).
+	 */
+	nonce?: string | ((event: H3Event) => string | undefined);
 }
 
 export const defineServerEntry = (options?: DefineServerEntryOptions): ServerEntry => {
@@ -72,7 +93,9 @@ export const defineServerEntry = (options?: DefineServerEntryOptions): ServerEnt
 
 		const assets = clientAssets.merge(...[rootAssets, serverAssets].filter(x => !!x));
 
-		if (!options?.disableEarlyHints) {
+		// early hints are pointless inside the prerender worker — nitro's
+		// prerenderer buffers the response to a file and discards them
+		if (!options?.disableEarlyHints && !event.req.headers.has("x-nitro-prerender")) {
 			const link = [
 				...assets.js.map(script => `<${script.href}>; rel=modulepreload`),
 				...assets.css.map(style => `<${style.href}>; rel=preload; as=style`),
@@ -86,6 +109,7 @@ export const defineServerEntry = (options?: DefineServerEntryOptions): ServerEnt
 		return (await handler())(event, {
 			assets,
 			head: typeof options?.head === "function" ? options.head(event) : options?.head,
+			nonce: typeof options?.nonce === "function" ? options.nonce(event) : options?.nonce,
 		});
 	};
 

package/src/vite/index.ts

@@ -1,8 +1,10 @@
 import { existsSync } from "node:fs";
+import { resolve } from "node:path";
 import type { NitroPluginConfig } from "nitro/vite";
 import { nitro } from "nitro/vite";
 import type { EnvironmentOptions, PluginOption } from "vite";
 import { islands } from "./islands";
+import { prerenderModule } from "./prerender";
 import { virtualAssets } from "./virtual-assets";
 import { virtualErrorHandler } from "./virtual-error-handler";
 import { virtualPages } from "./virtual-pages";
@@ -19,7 +21,11 @@ const yamf = (options?: YamfOptions): PluginOption[] => {
 	// TODO: extendable config
 	plugins.push({
 		name: "yamf:config",
-		config() {
+		config(config) {
+			// resolved against the vite root (not cwd) so running vite from
+			// another working directory does not silently drop the ssr entry
+			const root = config.root ?? process.cwd();
+
 			const ssrEnv: EnvironmentOptions = {
 				build: {
 					// TODO: figure out if this should be true
@@ -61,7 +67,7 @@ const yamf = (options?: YamfOptions): PluginOption[] => {
 					],
 				},
 				environments: {
-					...(existsSync("./src/server.tsx") ? { ssr: ssrEnv } : {}),
+					...(existsSync(resolve(root, "./src/server.tsx")) ? { ssr: ssrEnv } : {}),
 					client: {
 						build: {
 							rolldownOptions: {
@@ -82,16 +88,37 @@ const yamf = (options?: YamfOptions): PluginOption[] => {
 	plugins.push(virtualTemplate());
 	plugins.push(virtualRoot());
 
+	// registers the nitro module that makes prerender work (see prerenderModule)
+	plugins.push({
+		name: "yamf:prerender",
+		nitro: prerenderModule,
+	});
+
+	// reserved nitro keys are yamf-controlled and intentionally win over user
+	// values; everything else the user passes through wins. user publicAssets
+	// are merged with yamf's instead of being dropped
+	const {
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		serverDir: _serverDir,
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		renderer: _renderer,
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		compressPublicAssets: _compressPublicAssets,
+		publicAssets: userPublicAssets,
+		...userNitro
+	} = options?.nitro ?? {};
+
 	plugins.push(
 		nitro({
+			...userNitro,
 			serverDir: "./src",
 			renderer: false,
-			...options?.nitro,
 			compressPublicAssets: {
 				gzip: true,
 				brotli: true,
 			},
 			publicAssets: [
+				...(userPublicAssets ?? []),
 				{
 					baseURL: "assets",
 					dir: "./public/assets",

package/src/vite/islands.ts

@@ -5,6 +5,24 @@ import { Visitor } from "vite";
 
 const ISLAND_REGEX = /\.island\.(j|t)sx?$/;
 
+// inits that can plausibly evaluate to a component; anything else (object,
+// array, literal, class…) is left as a plain export with a warning
+const WRAPPABLE_INIT_TYPES = new Set([
+	"ArrowFunctionExpression",
+	"FunctionExpression",
+	"CallExpression",
+	"OptionalCallExpression",
+	"Identifier",
+	"ConditionalExpression",
+	"SequenceExpression",
+	"TSAsExpression",
+	"NonNullExpression",
+]);
+
+const isWrappableInit = (init: { type: string }): boolean => {
+	return WRAPPABLE_INIT_TYPES.has(init.type);
+};
+
 type Lang = NonNullable<ParserOptions["lang"]>;
 
 function langFromId(id: string): Lang {
@@ -42,6 +60,7 @@ export const islands = (): Plugin[] => {
 					s.prepend(`import __assets from "${id}?assets=client";\n`);
 
 					const seenExports = new Set<string>();
+					const warnings: string[] = [];
 
 					new Visitor({
 						ExportDefaultDeclaration(node) {
@@ -51,6 +70,9 @@ export const islands = (): Plugin[] => {
 								declaration.type !== "FunctionExpression" &&
 								declaration.type !== "ArrowFunctionExpression"
 							) {
+								warnings.push(
+									`${id}: export default <${declaration.type === "Identifier" ? "identifier" : declaration.type}> is not wrapped as an island — only function components are supported`,
+								);
 								return;
 							}
 
@@ -64,8 +86,20 @@ export const islands = (): Plugin[] => {
 						},
 						ExportNamedDeclaration(node) {
 							const declaration = node.declaration;
-							if (declaration?.type === "VariableDeclaration") {
-								const declarator = declaration.declarations[0];
+
+							if (!declaration) {
+								if (node.exportKind !== "type") {
+									warnings.push(
+										`${id}: export { … } statements are not wrapped as islands — export the component with \`export const\` or \`export function\``,
+									);
+								}
+								return;
+							}
+
+							if (declaration.type === "VariableDeclaration") {
+								const declarators = declaration.declarations;
+								const declarator = declarators[0];
+
 								if (
 									!declarator ||
 									declarator.id.type !== "Identifier" ||
@@ -74,7 +108,22 @@ export const islands = (): Plugin[] => {
 								) {
 									return;
 								}
+
 								const exportName = declarator.id.name;
+
+								if (!isWrappableInit(declarator.init)) {
+									warnings.push(
+										`${id}: export "${exportName}" does not look like a component — left as a plain export, not an island`,
+									);
+									return;
+								}
+
+								if (declarators.length > 1) {
+									warnings.push(
+										`${id}: only the first declarator of a multi-declarator export is wrapped as an island ("${exportName}") — split the declaration`,
+									);
+								}
+
 								seenExports.add(exportName);
 
 								// export const <name> = <init> ->
@@ -88,7 +137,7 @@ export const islands = (): Plugin[] => {
 									declarator.init.end,
 									`; export const ${exportName} = __runtime.createIsland(__wrap_${exportName}, "${exportName}", __assets)`,
 								);
-							} else if (declaration?.type === "FunctionDeclaration") {
+							} else if (declaration.type === "FunctionDeclaration") {
 								const fnId = declaration.id;
 								if (
 									!fnId ||
@@ -111,6 +160,10 @@ export const islands = (): Plugin[] => {
 							}
 						},
 					}).visit(program);
+
+					for (const warning of warnings) {
+						this.warn(warning);
+					}
 				}),
 			},
 		},
@@ -119,8 +172,9 @@ export const islands = (): Plugin[] => {
 			transform: {
 				order: "post",
 				handler: withMagicString(function (s) {
-					if (s.original.includes("__island_raw_import__")) {
-						s.replaceAll("__island_raw_import__", "import");
+					// the token is namespaced to avoid colliding with user code
+					if (s.original.includes("__yamf_raw_import__")) {
+						s.replaceAll("__yamf_raw_import__", "import");
 					}
 				}),
 			},

package/src/vite/prerender.ts

@@ -0,0 +1,27 @@
+import type { NitroModule } from "nitro/types";
+
+// Nitro's prerenderer is a standalone rolldown build (`nitro-prerender` preset)
+// that cannot run yamf's vite plugins, so `virtual:yamf:*` modules, the islands
+// transform, and the vite asset manifests do not exist there. Its auto-detected
+// serverEntry (src/server.tsx) would be bundled by rolldown and crash the
+// worker at init (`Received protocol 'virtual:'`). Disabling it lets prerender
+// requests fall through to the inherited renderer — nitro's vite ssr-renderer —
+// which dispatches them into the vite-built ssr service bundle: the exact code
+// path the production server uses.
+export const prerenderModule: NitroModule = {
+	name: "yamf:prerender",
+	setup(nitro) {
+		nitro.hooks.hook("prerender:config", config => {
+			config.serverEntry = false;
+		});
+
+		nitro.hooks.hook("prerender:generate", route => {
+			// static hosts (github-pages & friends) expect the not-found document
+			// at exactly /404.html; nitro would write /404 as 404/index.html
+			// (autoSubfolderIndex)
+			if (route.route === "/404" && !route.error && !route.skip) {
+				route.fileName = "404.html";
+			}
+		});
+	},
+};

package/src/vite/virtual-root.ts

@@ -1,3 +1,4 @@
+import { resolve } from "node:path";
 import { resolveModulePath } from "exsolve";
 import type { Plugin } from "vite";
 import { js } from "../shared/utils";
@@ -8,8 +9,15 @@ export const virtualRoot = (): Plugin => {
 	const virtualModuleId = "virtual:yamf:root";
 	const resolvedVirtualModuleId = "\0" + virtualModuleId;
 
+	// resolved against the vite root (not cwd) so running vite from another
+	// working directory does not silently skip the root layout
+	let root = process.cwd();
+
 	return {
 		name: "yamf:virtual-root",
+		configResolved(config) {
+			root = config.root;
+		},
 		resolveId(id) {
 			if (id === virtualModuleId) {
 				return resolvedVirtualModuleId;
@@ -22,13 +30,15 @@ export const virtualRoot = (): Plugin => {
 				return;
 			}
 
-			const root = resolveModulePath(ROOT_PATH, {
+			const rootPath = resolve(root, ROOT_PATH);
+
+			const rootModule = resolveModulePath(rootPath, {
 				try: true,
 				suffixes: ["", "/index"],
 				extensions: [".tsx", ".jsx", ".ts", ".js", ".mjs", ".cjs", ".mts", ".cts"],
 			});
 
-			if (!root) {
+			if (!rootModule) {
 				return js`
 const Root = null;
 const rootAssets = null;
@@ -38,8 +48,8 @@ export { Root, rootAssets };
 			}
 
 			return js`
-import Root from "${ROOT_PATH}";
-import rootAssets from "${ROOT_PATH}?assets=ssr";
+import Root from "${rootModule}";
+import rootAssets from "${rootModule}?assets=ssr";
 
 export { Root, rootAssets };
 `.trim();

package/src/vite/virtual-template.ts

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { relative } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 import type { Plugin } from "vite";
 import { js } from "../shared/utils";
 
@@ -19,8 +19,16 @@ export const virtualTemplate = (): Plugin => {
 	const virtualModuleId = "virtual:yamf:template";
 	const resolvedVirtualModuleId = "\0" + virtualModuleId;
 
+	// resolved against the vite root (not cwd) so running vite from another
+	// working directory — monorepo tooling, turbo, etc — does not silently
+	// fall back to the default template
+	let root = process.cwd();
+
 	return {
 		name: "yamf:virtual-template",
+		configResolved(config) {
+			root = config.root;
+		},
 		resolveId(id) {
 			if (id === virtualModuleId) {
 				return resolvedVirtualModuleId;
@@ -34,7 +42,7 @@ export const virtualTemplate = (): Plugin => {
 			}
 
 			try {
-				const template = await readFile(TEMPLATE_PATH, "utf8");
+				const template = await readFile(resolve(root, TEMPLATE_PATH), "utf8");
 
 				return js`export const template = ${JSON.stringify(template)};`;
 			} catch (error) {
@@ -46,7 +54,11 @@ export const virtualTemplate = (): Plugin => {
 			}
 		},
 		handleHotUpdate({ file, server }) {
-			if (relative(file, TEMPLATE_PATH) === "") {
+			if (!isAbsolute(file)) {
+				return;
+			}
+
+			if (relative(resolve(root, TEMPLATE_PATH), file) === "") {
 				const mod = server.moduleGraph.getModuleById(resolvedVirtualModuleId);
 
 				if (mod) {