@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/vite/dev-middleware.ts

@@ -0,0 +1,142 @@
+/**
+ * Dev SSR Middleware
+ * Runs the app server entry inside the Vite dev server
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ViteDevServer } from "vite";
+import type { SolidFrameworkConfig } from "#app/types";
+
+interface ServerEntryModule {
+	default?: (request: Request) => Promise<Response>;
+	fetch?: (request: Request) => Promise<Response>;
+	handler?: (request: Request) => Promise<Response>;
+}
+
+const toWebRequest = async (req: IncomingMessage): Promise<Request> => {
+	const host = req.headers.host ?? "localhost";
+	const url = `http://${host}${req.url ?? "/"}`;
+	const method = req.method ?? "GET";
+
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(req.headers)) {
+		if (value === undefined) continue;
+		headers.set(key, Array.isArray(value) ? value.join(", ") : value);
+	}
+
+	if (method === "GET" || method === "HEAD") {
+		return new Request(url, { method, headers });
+	}
+
+	const chunks: Buffer[] = [];
+	for await (const chunk of req) chunks.push(chunk as Buffer);
+	return new Request(url, {
+		method,
+		headers,
+		body: Buffer.concat(chunks),
+	});
+};
+
+const escapeHtml = (text: string): string =>
+	text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+/**
+ * Dev error overlay — styled page with the SSR stack, mirroring the
+ * vite error overlay experience for render-time failures
+ */
+const errorOverlayHtml = (error: Error): string =>
+	`<!doctype html><html><head><meta charset="utf-8"><title>SSR Error</title>` +
+	`<style>body{margin:0;font:14px/1.5 ui-monospace,monospace;background:#1a0505;color:#fca5a5}` +
+	`.wrap{padding:2rem;max-width:960px;margin:auto}h1{color:#ef4444;font-size:1.25rem}` +
+	`pre{background:#2a0a0a;border:1px solid #7f1d1d;border-radius:8px;padding:1rem;overflow:auto;white-space:pre-wrap}</style>` +
+	`</head><body><div class="wrap"><h1>[solid-framework] SSR render error</h1>` +
+	`<pre>${escapeHtml(error.stack ?? error.message)}</pre></div></body></html>`;
+
+const writeResponse = async (
+	res: ServerResponse,
+	response: Response,
+): Promise<void> => {
+	res.statusCode = response.status;
+	response.headers.forEach((value, key) => {
+		res.setHeader(key, value);
+	});
+
+	if (!response.body) {
+		res.end();
+		return;
+	}
+
+	const reader = response.body.getReader();
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			res.write(Buffer.from(value));
+		}
+	} finally {
+		res.end();
+	}
+};
+
+/**
+ * Vite middleware factory — SSRs page requests through the app server entry
+ */
+export const createSsrMiddleware = (
+	server: ViteDevServer,
+	config: SolidFrameworkConfig,
+): ((
+	req: IncomingMessage,
+	res: ServerResponse,
+	next: (err?: unknown) => void,
+) => void) => {
+	return (req, res, next) => {
+		const pathname = req.url?.split("?")[0] ?? "/";
+
+		// Framework endpoints carry dots too (sitemap.xml, openapi.json)
+		// — they must reach the server entry, not Vite's static fallback
+		const frameworkPath =
+			pathname === "/sitemap.xml" ||
+			pathname === "/robots.txt" ||
+			pathname === "/favicon.ico" ||
+			pathname.startsWith("/_server/") ||
+			pathname.startsWith("/_docs/") ||
+			pathname === "/_og" ||
+			pathname === "/_image";
+
+		// Let Vite internals and static assets pass through — everything
+		// else (pages, api prefixes, server fns, actions) goes to the entry
+		if (
+			!frameworkPath &&
+			(pathname.startsWith("/@") ||
+				pathname.startsWith("/node_modules/") ||
+				pathname.startsWith("/src/") ||
+				(pathname.includes(".") && !pathname.endsWith("/")))
+		) {
+			next();
+			return;
+		}
+
+		void (async () => {
+			try {
+				const mod = (await server.ssrLoadModule(
+					`/${config.entries.server}`,
+				)) as ServerEntryModule;
+				const handler = mod.default ?? mod.fetch ?? mod.handler;
+				if (!handler) {
+					throw new Error(
+						`[solid-framework] ${config.entries.server} must export a fetch handler (default, fetch, or handler)`,
+					);
+				}
+
+				const request = await toWebRequest(req);
+				const response = await handler(request);
+				await writeResponse(res, response);
+			} catch (error) {
+				server.ssrFixStacktrace(error as Error);
+				res.statusCode = 500;
+				res.setHeader("Content-Type", "text/html; charset=utf-8");
+				res.end(errorOverlayHtml(error as Error));
+			}
+		})();
+	};
+};

package/src/vite/index.ts

@@ -0,0 +1,9 @@
+// Public API - @wrikka/solid-framework/vite
+
+export * from "./auto-imports";
+export * from "./dev-middleware";
+export * from "./plugin";
+export * from "./prerender";
+export * from "./server-fn-ids";
+export * from "./types";
+export * from "./virtual-modules";

package/src/vite/plugin.ts

@@ -0,0 +1,277 @@
+/**
+ * solidFramework Vite Plugin
+ * Single orchestrating plugin — router codegen, virtual modules,
+ * server-module boundary, auto-imports and the dev SSR middleware
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { basename, join, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { Plugin } from "vite";
+import { resolveConfig } from "#app/modules/config";
+import { buildRouteManifest } from "#app/modules/file-routes";
+import { solidRouterPlugin } from "#router/vite-plugin";
+import { FRAMEWORK_AUTO_IMPORTS, injectAutoImports } from "./auto-imports";
+import { createSsrMiddleware } from "./dev-middleware";
+import { prerenderToDisk } from "./prerender";
+import { injectServerFnIds } from "./server-fn-ids";
+import type { SolidFrameworkPluginOptions } from "./types";
+import { VIRTUAL_CONFIG, VIRTUAL_ROUTES, VIRTUAL_SERVER_FNS } from "./types";
+import {
+	configModuleCode,
+	isServerModuleId,
+	routesModuleCode,
+	serverFnsModuleCode,
+	serverStubCode,
+} from "./virtual-modules";
+
+const RESOLVED_PREFIX = "\0";
+
+const resolveVirtualId = (id: string): string => `${RESOLVED_PREFIX}${id}`;
+
+export const solidFramework = (
+	options: SolidFrameworkPluginOptions = {},
+): Plugin[] => {
+	const config = resolveConfig(options.config);
+
+	const autoImportMap =
+		options.autoImports === false
+			? null
+			: {
+					...FRAMEWORK_AUTO_IMPORTS,
+					...(typeof options.autoImports === "object"
+						? options.autoImports
+						: {}),
+				};
+
+	let rootDir = "";
+	let ssrOutDir = "dist/server";
+	// `instrumentation.ts` convention — discovered at project/src root
+	let instrumentationPath: string | undefined;
+
+	const core: Plugin = {
+		name: "solid-framework",
+		enforce: "pre",
+
+		configResolved(resolved) {
+			rootDir = resolved.root;
+			if (process.env.SOLID_SSR_BUILD === "1") {
+				ssrOutDir = resolved.build.outDir;
+			}
+			// instrumentation.ts convention — first match wins
+			for (const dir of [resolved.root, join(resolved.root, "src")]) {
+				for (const ext of ["ts", "tsx"]) {
+					const candidate = join(dir, `instrumentation.${ext}`);
+					if (existsSync(candidate)) {
+						instrumentationPath = candidate.split(sep).join("/");
+					}
+				}
+			}
+		},
+
+		config(_userConfig, env) {
+			return {
+				ssr: {
+					noExternal: ["@wrikka/solid-framework"],
+				},
+				// @wrikka/web-server-toolkit is a runtime (bun) dependency — keep it
+				// external in SSR builds so rolldown never opens its dist bundle
+				...(env.isSsrBuild === true
+					? {
+							build: {
+								rollupOptions: {
+									external: ["@wrikka/web-server-toolkit", /^bun(:|$)/],
+								},
+							},
+						}
+					: {}),
+				server: {
+					watch: { ignored: ["**/dist/**"] },
+				},
+			};
+		},
+
+		resolveId(id, _importer, resolveOptions) {
+			if (
+				id === VIRTUAL_CONFIG ||
+				id === VIRTUAL_ROUTES ||
+				id === VIRTUAL_SERVER_FNS
+			) {
+				return resolveVirtualId(id);
+			}
+			// @wrikka/web-server-toolkit is server-only — stub it out of client bundles
+			if (id === "@wrikka/web-server-toolkit" && resolveOptions?.ssr !== true) {
+				return `${RESOLVED_PREFIX}web-server`;
+			}
+			return null;
+		},
+
+		load(id, loadOptions) {
+			if (id.startsWith(RESOLVED_PREFIX)) {
+				const virtual = id.slice(RESOLVED_PREFIX.length);
+				if (virtual === VIRTUAL_CONFIG)
+					// instrumentation hooks are server-only — merge only in SSR builds
+					return configModuleCode(
+						config,
+						loadOptions?.ssr === true ? instrumentationPath : undefined,
+					);
+				if (virtual === VIRTUAL_ROUTES)
+					return routesModuleCode(config.routesDir);
+				if (virtual === VIRTUAL_SERVER_FNS) return serverFnsModuleCode();
+				if (virtual === "web-server") {
+					return `const fail = () => { throw new Error("[solid-framework] @wrikka/web-server-toolkit is server-only and cannot run on the client"); };\nexport const createRequestHandler = fail;\nexport default fail;\n`;
+				}
+				return null;
+			}
+
+			// .server.ts boundary — stub server-only modules outside SSR builds
+			if (isServerModuleId(id) && loadOptions?.ssr !== true) {
+				return serverStubCode(id);
+			}
+			return null;
+		},
+
+		transform(code, id) {
+			if (!/\.[jt]sx?$/.test(id) || id.includes("node_modules")) return null;
+			if (isServerModuleId(id)) return null;
+
+			let next = autoImportMap ? injectAutoImports(code, autoImportMap) : null;
+			let current = next ?? code;
+			const withIds = injectServerFnIds(current, id);
+			if (withIds !== current) {
+				current = withIds;
+				next = current;
+			}
+			for (const plugin of config.plugins ?? []) {
+				const out = plugin.transform?.(current, id);
+				if (out != null) {
+					current = out;
+					next = out;
+				}
+			}
+			return next === null ? null : { code: current, map: null };
+		},
+
+		buildStart() {
+			// Notify plugins of the resolved route manifest — scan runs on
+			// the node side so build/dev share one source of truth
+			if (!existsSync(config.routesDir)) return;
+			const files: string[] = [];
+			const walk = (dir: string) => {
+				for (const entry of readdirSync(dir, { withFileTypes: true })) {
+					const full = join(dir, entry.name);
+					if (entry.isDirectory()) walk(full);
+					else files.push(full.split(sep).join("/"));
+				}
+			};
+			walk(config.routesDir);
+			const manifest = buildRouteManifest(files, config.routesDir);
+			for (const plugin of config.plugins ?? []) {
+				plugin.routesResolved?.(manifest);
+			}
+		},
+
+		handleHotUpdate({ file, server }) {
+			// Route file edits trigger a full reload — the manifest and
+			// convention wiring (layouts/boundaries) can change shape
+			const routesRoot = `${config.routesDir.split("/").join(sep)}${sep}`;
+			if (file.split("/").join(sep).startsWith(routesRoot)) {
+				server.ws.send({ type: "full-reload" });
+			}
+		},
+
+		configureServer(server) {
+			if (options.ssrMiddleware === false) return;
+			server.middlewares.use(createSsrMiddleware(server, config));
+		},
+
+		generateBundle(_options, bundle) {
+			if (process.env.SOLID_SSR_BUILD === "1") return;
+			// Preload manifest — entry chunks + css for head hints
+			const entries = Object.values(bundle)
+				.filter(
+					(o) =>
+						(o.type === "chunk" && o.isEntry) || o.fileName.endsWith(".css"),
+				)
+				.map((o) => `/${o.fileName}`);
+			if (entries.length) {
+				this.emitFile({
+					type: "asset",
+					fileName: "preload-manifest.json",
+					source: JSON.stringify({ preloads: entries }),
+				});
+			}
+			// PWA — emit sw.js + manifest.webmanifest into the client build
+			if (!config.pwa) return;
+			const pwa = config.pwa;
+			const precache = [
+				"/",
+				...(pwa.precache ?? []),
+				...(pwa.manifest ? ["/manifest.webmanifest"] : []),
+			];
+			this.emitFile({
+				type: "asset",
+				fileName: "sw.js",
+				source: `const CACHE="sf-v1";const PRECACHE=${JSON.stringify(precache)};self.addEventListener("install",e=>{e.waitUntil(caches.open(CACHE).then(c=>c.addAll(PRECACHE)).then(()=>self.skipWaiting()))});self.addEventListener("activate",e=>{e.waitUntil(self.clients.claim())});self.addEventListener("fetch",e=>{if(e.request.method!=="GET")return;const nav=e.request.mode==="navigate"||(e.request.headers.get("accept")||"").includes("text/html");if(nav){e.respondWith(fetch(e.request).then(res=>{const copy=res.clone();caches.open(CACHE).then(c=>c.put(e.request,copy));return res}).catch(()=>caches.match(e.request).then(r=>r||caches.match("/"))));return}e.respondWith(caches.match(e.request).then(r=>r||fetch(e.request).then(res=>{const copy=res.clone();caches.open(CACHE).then(c=>c.put(e.request,copy));return res})))});`,
+			});
+			if (pwa.manifest) {
+				this.emitFile({
+					type: "asset",
+					fileName: "manifest.webmanifest",
+					source: JSON.stringify({
+						name: pwa.manifest.name ?? "app",
+						short_name: pwa.manifest.shortName ?? pwa.manifest.name ?? "app",
+						start_url: pwa.manifest.startUrl ?? "/",
+						display: pwa.manifest.display ?? "standalone",
+						background_color: pwa.manifest.background ?? "#ffffff",
+						theme_color: pwa.manifest.theme ?? "#000000",
+						icons: pwa.manifest.icons ?? [],
+					}),
+				});
+			}
+		},
+
+		async closeBundle() {
+			// Build-time prerender — after the SSR bundle is written, load
+			// the built server entry and render configured routes to disk
+			if (process.env.SOLID_SSR_BUILD !== "1" || !config.prerender) return;
+			const pre = config.prerender;
+			if (!pre.routes?.length && !pre.crawlLinks) return;
+
+			const entryFile = join(
+				rootDir || ".",
+				ssrOutDir,
+				basename(config.entries.server).replace(/\.[jt]sx?$/, ".js"),
+			);
+			const mod = (await import(pathToFileURL(entryFile).href)) as {
+				default?: (request: Request) => Promise<Response>;
+			};
+			const handler = mod.default;
+			if (typeof handler !== "function") {
+				console.warn(
+					"[solid-framework] prerender skipped — server entry has no default fetch handler",
+				);
+				return;
+			}
+
+			const written = await prerenderToDisk(handler, {
+				routes: pre.routes,
+				crawlLinks: pre.crawlLinks,
+				outDir: pre.outDir ?? join(rootDir || ".", "dist"),
+			});
+			console.log(
+				`[solid-framework] prerendered ${written.length} route(s): ${written
+					.map((w) => w.path)
+					.join(", ")}`,
+			);
+		},
+	};
+
+	const plugins: Plugin[] = [core];
+
+	if (options.router !== false) {
+		plugins.push(solidRouterPlugin(options.router ?? {}));
+	}
+
+	return plugins;
+};

package/src/vite/prerender.ts

@@ -0,0 +1,72 @@
+/**
+ * Build-time Prerender
+ * Renders routes through the built server entry and writes static
+ * HTML to outDir — the SSG equivalent of Nitro's prerender, with
+ * crawlLinks discovering pages from rendered anchors
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Same-origin links found in rendered HTML — `href="/path"` */
+export const extractLinks = (html: string): string[] => {
+	const links = new Set<string>();
+	for (const match of html.matchAll(/href="(\/[^"#]*)"/g)) {
+		const path = (match[1] ?? "").split("?")[0];
+		if (path && !path.startsWith("//")) links.add(path);
+	}
+	return [...links];
+};
+
+export interface PrerenderResult {
+	path: string;
+	file: string;
+	status: number;
+}
+
+const outFile = (outDir: string, path: string): string =>
+	join(
+		outDir,
+		path === "/"
+			? "index.html"
+			: `${path.replace(/^\/+|\/+$/g, "")}/index.html`,
+	);
+
+export const prerenderToDisk = async (
+	handler: (request: Request) => Promise<Response>,
+	options: {
+		routes?: string[];
+		crawlLinks?: boolean;
+		outDir: string;
+		/** Base origin for constructed requests — default http://localhost */
+		base?: string;
+	},
+): Promise<PrerenderResult[]> => {
+	const base = options.base ?? "http://localhost";
+	const queue = [...(options.routes ?? ["/"])];
+	const seen = new Set<string>();
+	const written: PrerenderResult[] = [];
+
+	while (queue.length > 0) {
+		const path = queue.shift() as string;
+		if (seen.has(path)) continue;
+		seen.add(path);
+
+		const response = await handler(new Request(`${base}${path}`));
+		if (!response.ok) continue;
+
+		const html = await response.text();
+		const file = outFile(options.outDir, path);
+		mkdirSync(dirname(file), { recursive: true });
+		writeFileSync(file, html);
+		written.push({ path, file, status: response.status });
+
+		if (options.crawlLinks) {
+			for (const link of extractLinks(html)) {
+				if (!seen.has(link)) queue.push(link);
+			}
+		}
+	}
+
+	return written;
+};

package/src/vite/server-fn-ids.ts

@@ -0,0 +1,52 @@
+/**
+ * Server Fn Id Transform
+ * Injects stable ids into `createServerFn({ ... })` calls that omit
+ * `id` — the hash derives from file path + call index so the client
+ * and server bundles agree without a runtime handshake
+ */
+
+import { createHash } from "node:crypto";
+
+const stableId = (fileId: string, index: number): string =>
+	`sf_${createHash("sha256").update(`${fileId}#${index}`).digest("hex").slice(0, 12)}`;
+
+/** Find the closing brace for an object literal starting at `open` */
+const matchingBrace = (code: string, open: number): number => {
+	let depth = 0;
+	for (let i = open; i < code.length; i++) {
+		const ch = code[i];
+		if (ch === "{") depth++;
+		else if (ch === "}") {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+};
+
+export const injectServerFnIds = (code: string, fileId: string): string => {
+	if (!code.includes("createServerFn(")) return code;
+
+	const pattern = /createServerFn\s*\(\s*\{/g;
+	let out = "";
+	let cursor = 0;
+	let index = 0;
+	let match: RegExpExecArray | null;
+
+	// biome-ignore lint/suspicious/noAssignInExpressions: classic exec loop
+	while ((match = pattern.exec(code)) !== null) {
+		const open = match.index + match[0].length - 1; // position of "{"
+		const close = matchingBrace(code, open);
+		if (close === -1) break;
+		const body = code.slice(open + 1, close);
+		index++;
+
+		if (/(^|[\s,}])id\s*:/.test(body)) continue; // explicit id kept
+
+		out += code.slice(cursor, open + 1);
+		out += `id: "${stableId(fileId, index)}",`;
+		cursor = open + 1;
+	}
+
+	return cursor > 0 ? out + code.slice(cursor) : code;
+};

package/src/vite/types/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Vite Plugin Types
+ */
+
+import type { SolidFrameworkConfig } from "#app/types";
+import type { SolidRouterPluginOptions } from "#router/vite-plugin";
+
+export interface SolidFrameworkPluginOptions {
+	/** Framework config (also emitted to virtual:solid-framework/config) */
+	config?: Partial<SolidFrameworkConfig>;
+	/** Router plugin options — pass false to disable route codegen plugin */
+	router?: SolidRouterPluginOptions | false;
+	/**
+	 * Auto-import map: export name → module specifier.
+	 * true = framework defaults; false = disabled; object = merged with defaults
+	 */
+	autoImports?: Record<string, string | string[]> | boolean;
+	/** Serve SSR through the dev middleware — default true */
+	ssrMiddleware?: boolean;
+}
+
+export const VIRTUAL_CONFIG = "virtual:solid-framework/config";
+export const VIRTUAL_ROUTES = "virtual:solid-framework/routes";
+export const VIRTUAL_SERVER_FNS = "virtual:solid-framework/server-fns";

package/src/vite/virtual-modules.ts

@@ -0,0 +1,68 @@
+/**
+ * Virtual Modules
+ * Code emitted for framework virtual imports
+ */
+
+import type { SolidFrameworkConfig } from "#app/types";
+
+export const configModuleCode = (
+	config: SolidFrameworkConfig,
+	instrumentationPath?: string,
+): string =>
+	instrumentationPath
+		? [
+				`import * as _instr from ${JSON.stringify(instrumentationPath)};`,
+				`export default Object.assign(${JSON.stringify(config)}, {`,
+				"	instrumentation: {",
+				"		register: _instr.register,",
+				"		onRequest: _instr.onRequest,",
+				"		onError: _instr.onError,",
+				"	},",
+				"});",
+			].join("\n")
+		: `export default ${JSON.stringify(config)};`;
+
+/**
+ * Route manifest — Vite glob import over the routes directory, plus a
+ * prebuilt RouteManifest for <FileRoutes>. Convention files
+ * (error/loading/not-found/layout) are included in the modules map.
+ */
+export const routesModuleCode = (routesDir: string): string =>
+	[
+		'import { buildRouteManifest, preloadFileRoute } from "@wrikka/solid-framework/internal";',
+		`const modules = import.meta.glob("/${routesDir}/**/*.{tsx,ts,jsx,js}");`,
+		`export const routeFiles = Object.keys(modules).map((file) => file.slice(1));`,
+		`export const routeModules = Object.fromEntries(Object.entries(modules).map(([k, v]) => [k.slice(1), v]));`,
+		`export const manifest = buildRouteManifest(routeFiles, ${JSON.stringify(routesDir)});`,
+		"export const preloadRoute = (path) => preloadFileRoute(path, manifest, routeModules);",
+		"export default manifest;",
+	].join("\n");
+
+/**
+ * Server function registry — eager glob of server modules so every
+ * createServerFn descriptor registers itself on the server bundle.
+ * Conventions:
+ *   *.server.ts  — server-only code (stubbed out of client bundles)
+ *   *.fn.ts      — isomorphic createServerFn definitions (client ships the
+ *                  remote caller only; handler executes server-side)
+ */
+export const serverFnsModuleCode = (): string =>
+	[
+		'const modules = import.meta.glob("/src/**/*.{server,fn}.{ts,tsx}", { eager: true });',
+		"export const serverModules = modules;",
+		"export default modules;",
+	].join("\n");
+
+/**
+ * Stub emitted when a .server module leaks into the client bundle
+ */
+export const serverStubCode = (id: string): string =>
+	[
+		`throw new Error(`,
+		`  "[solid-framework] \\"${id}\\" is a .server module and cannot be imported from the client. ` +
+			`Move the import into a loader, createServerFn handler, or .server.ts file."`,
+		`);`,
+	].join("\n");
+
+export const isServerModuleId = (id: string): boolean =>
+	/\.server\.(ts|tsx|js|jsx|mts|cts)$/.test(id.split("?")[0] ?? id);