blumenjs 0.2.3 → 0.2.5

package/dist/cli/blumen.js

@@ -842,6 +842,7 @@ function getTemplateFiles(projectName, template) {
     ["node-ssr/server.ts", readProjectFile("node-ssr/server.ts")],
     ["go-server/main.go", readProjectFile("go-server/main.go")],
     ["scripts/generate-routes.ts", readProjectFile("scripts/generate-routes.ts")],
+    ["scripts/generate-api-routes.ts", readProjectFile("scripts/generate-api-routes.ts")],
     // Placeholder
     ["static/js/.gitkeep", ""],
     // Docker support (production deployment)

package/dist/cli/commands/create.js

@@ -526,6 +526,7 @@ function getTemplateFiles(projectName, template) {
     ["node-ssr/server.ts", readProjectFile("node-ssr/server.ts")],
     ["go-server/main.go", readProjectFile("go-server/main.go")],
     ["scripts/generate-routes.ts", readProjectFile("scripts/generate-routes.ts")],
+    ["scripts/generate-api-routes.ts", readProjectFile("scripts/generate-api-routes.ts")],
     // Placeholder
     ["static/js/.gitkeep", ""],
     // Docker support (production deployment)

package/dist/templates/app/shared/RouterContext.tsx

@@ -212,6 +212,14 @@ export function RouterProvider({
 		return () => window.removeEventListener("popstate", onPopState);
 	}, []);
 
+	// Track whether hydration is complete. During hydration, we skip
+	// Suspense because the lazy chunk hasn't loaded yet and Suspense
+	// would show a fallback that mismatches the server HTML.
+	const [hydrated, setHydrated] = useState(false);
+	useEffect(() => {
+		setHydrated(true);
+	}, []);
+
 	// ── Render ──────────────────────────────────────────────────
 	const contextValue: RouterContextValue = { path, params, navigate };
 
@@ -220,6 +228,19 @@ export function RouterProvider({
 	// 2. Otherwise — show the page component
 	const LoadingComp = loadingComponent;
 
+	// During initial hydration, render App directly (no Suspense/ErrorBoundary)
+	// to match the SSR output exactly. After hydration, wrap with Suspense
+	// for lazy-loaded navigation.
+	const pageContent = hydrated ? (
+		<BlumenErrorBoundary>
+			<Suspense fallback={LoadingComp ? <LoadingComp /> : <DefaultLoading />}>
+				<App Component={PageComponent} pageProps={pageProps} />
+			</Suspense>
+		</BlumenErrorBoundary>
+	) : (
+		<App Component={PageComponent} pageProps={pageProps} />
+	);
+
 	return (
 		<RouterContext.Provider value={contextValue}>
 			{isLoading && LoadingComp ? (
@@ -230,11 +251,7 @@ export function RouterProvider({
 				<div
 					className={`page-transition ${transitioning ? "page-transition-exit" : "page-transition-active"}`}
 				>
-					<BlumenErrorBoundary>
-						<Suspense fallback={LoadingComp ? <LoadingComp /> : <DefaultLoading />}>
-							<App Component={PageComponent} pageProps={pageProps} />
-						</Suspense>
-					</BlumenErrorBoundary>
+					{pageContent}
 				</div>
 			)}
 		</RouterContext.Provider>

package/dist/templates/node-ssr/server.ts

@@ -342,8 +342,9 @@ async function handleRender(
 		};
 
 		// Render React to HTML
-		// Wrap in the same page-transition div that the client-side
-		// RouterProvider renders, so hydration trees match exactly.
+		// Must match the client's INITIAL hydration tree exactly:
+		//   div.page-transition > App
+		// (Client adds Suspense/ErrorBoundary AFTER hydration via useEffect)
 		const appElement = React.createElement(
 			"div",
 			{ className: "page-transition page-transition-active" },

package/dist/templates/scripts/generate-api-routes.ts

@@ -0,0 +1,236 @@
+/**
+ * Blumen API Route Generator
+ *
+ * Scans app/api/ recursively for route.ts files and generates:
+ *   node-ssr/generated-api-routes.ts — API route map for the SSR server
+ *
+ * Convention:
+ *   - app/api/users/route.ts       → /api/users
+ *   - app/api/users/[id]/route.ts  → /api/users/[id]
+ *   - Only `route.ts` files are scanned (not .tsx — API routes don't render)
+ *   - Exported function names determine allowed HTTP methods:
+ *     GET, POST, PUT, DELETE, PATCH
+ *
+ * Usage:  npx tsx scripts/generate-api-routes.ts
+ *         (Also called automatically by generate-routes.ts)
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as ts from "typescript";
+
+const API_DIR = path.resolve("app/api");
+const API_OUTPUT = path.resolve("node-ssr/generated-api-routes.ts");
+
+const HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH"] as const;
+
+interface APIRouteEntry {
+	/** The URL path, e.g. "/api/users" or "/api/users/[id]" */
+	route: string;
+	/** Safe identifier for imports */
+	routeId: string;
+	/** Import path relative to the api dir */
+	importPath: string;
+	/** Regex string for matching the route */
+	patternStr: string;
+	/** Extracted parameter keys */
+	keys: string[];
+	/** HTTP methods exported by this route */
+	methods: string[];
+}
+
+/**
+ * Check if a file exports a named identifier at the top level.
+ * Uses TypeScript AST to avoid false positives from strings/comments.
+ */
+function hasNamedExport(filePath: string, content: string, exportName: string): boolean {
+	const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+	let found = false;
+
+	ts.forEachChild(sourceFile, (node) => {
+		if (ts.isFunctionDeclaration(node)) {
+			const isExported = node.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword);
+			if (isExported && node.name?.text === exportName) found = true;
+		} else if (ts.isVariableStatement(node)) {
+			const isExported = node.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword);
+			if (isExported) {
+				for (const decl of node.declarationList.declarations) {
+					if (ts.isIdentifier(decl.name) && decl.name.text === exportName) found = true;
+				}
+			}
+		} else if (ts.isExportDeclaration(node)) {
+			if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+				for (const element of node.exportClause.elements) {
+					if (element.name.text === exportName) found = true;
+				}
+			}
+		}
+	});
+
+	return found;
+}
+
+function scanAPIDir(dir: string, baseDir: string = dir): APIRouteEntry[] {
+	if (!fs.existsSync(dir)) return [];
+
+	let results: APIRouteEntry[] = [];
+	const items = fs.readdirSync(dir, { withFileTypes: true });
+
+	for (const item of items) {
+		const fullPath = path.join(dir, item.name);
+
+		if (item.isDirectory()) {
+			results = results.concat(scanAPIDir(fullPath, baseDir));
+		} else if (item.isFile() && item.name === "route.ts") {
+			const relDir = path.relative(baseDir, dir).replace(/\\/g, "/");
+			const routePath = "/api" + (relDir ? "/" + relDir.toLowerCase() : "");
+
+			// Generate safe identifier
+			const routeId = "api_" + (relDir || "root").replace(/[^a-zA-Z0-9]/g, "_");
+
+			// Parse bracket syntax for dynamic parameters
+			const keys: string[] = [];
+			let patternStr = routePath.replace(/\[([^\]]+)\]/g, (_, key) => {
+				keys.push(key);
+				return "([^/]+)";
+			});
+			patternStr = `^${patternStr}$`;
+
+			// Detect exported HTTP method handlers
+			const content = fs.readFileSync(fullPath, "utf-8");
+			const methods: string[] = [];
+			for (const method of HTTP_METHODS) {
+				if (hasNamedExport(fullPath, content, method)) {
+					methods.push(method);
+				}
+			}
+
+			if (methods.length === 0) {
+				console.warn(`     ⚠️  ${routePath} — no HTTP method exports found, skipping`);
+				continue;
+			}
+
+			const importPath = relDir ? relDir + "/route" : "route";
+
+			results.push({
+				route: routePath,
+				routeId,
+				importPath,
+				patternStr,
+				keys,
+				methods,
+			});
+		}
+	}
+
+	// Sort: specific routes before dynamic ones
+	results.sort((a, b) => {
+		const aIsDynamic = a.route.includes("[");
+		const bIsDynamic = b.route.includes("[");
+		if (aIsDynamic && !bIsDynamic) return 1;
+		if (!aIsDynamic && bIsDynamic) return -1;
+		return a.route.localeCompare(b.route);
+	});
+
+	return results;
+}
+
+function generateAPIRouteFile(routes: APIRouteEntry[]): string {
+	const header = [
+		"// ┌─────────────────────────────────────────────┐",
+		"// │  AUTO-GENERATED — DO NOT EDIT               │",
+		"// │  Run `npm run routes` to regenerate          │",
+		"// └─────────────────────────────────────────────┘",
+		"",
+	];
+
+	// Generate imports
+	const imports: string[] = [];
+	for (const r of routes) {
+		const namedImports = r.methods
+			.map(m => `${m} as ${m.toLowerCase()}_${r.routeId}`)
+			.join(", ");
+		imports.push(
+			`import { ${namedImports} } from "../app/api/${r.importPath}";`,
+		);
+	}
+
+	// Generate type and route array
+	const body = [
+		"",
+		"export interface APIRouteDef {",
+		"\tpath: string;",
+		"\tpattern: RegExp;",
+		"\tkeys: string[];",
+		"\thandlers: Record<string, Function>;",
+		"}",
+		"",
+		"export const apiRoutes: APIRouteDef[] = [",
+	];
+
+	for (const r of routes) {
+		const handlersObj = r.methods
+			.map(m => `${m}: ${m.toLowerCase()}_${r.routeId}`)
+			.join(", ");
+		body.push(`\t{`);
+		body.push(`\t\tpath: "${r.route}",`);
+		body.push(`\t\tpattern: new RegExp("${r.patternStr.replace(/\\/g, "\\\\")}"),`);
+		body.push(`\t\tkeys: ${r.keys.length > 0 ? `["${r.keys.join('", "')}"]` : "[]"},`);
+		body.push(`\t\thandlers: { ${handlersObj} }`);
+		body.push(`\t},`);
+	}
+
+	body.push("];");
+	body.push("");
+
+	return [...header, ...imports, ...body].join("\n");
+}
+
+export function generateAPIRoutes(): APIRouteEntry[] {
+	if (!fs.existsSync(API_DIR)) {
+		// No app/api/ directory — generate empty file
+		const emptyFile = [
+			"// No API routes found (app/api/ directory does not exist)",
+			"",
+			"export interface APIRouteDef {",
+			"\tpath: string;",
+			"\tpattern: RegExp;",
+			"\tkeys: string[];",
+			"\thandlers: Record<string, Function>;",
+			"}",
+			"",
+			"export const apiRoutes: APIRouteDef[] = [];",
+			"",
+		].join("\n");
+		fs.mkdirSync(path.dirname(API_OUTPUT), { recursive: true });
+		fs.writeFileSync(API_OUTPUT, emptyFile, "utf-8");
+		return [];
+	}
+
+	const routes = scanAPIDir(API_DIR);
+
+	const content = generateAPIRouteFile(routes);
+	fs.mkdirSync(path.dirname(API_OUTPUT), { recursive: true });
+	fs.writeFileSync(API_OUTPUT, content, "utf-8");
+
+	return routes;
+}
+
+// Allow standalone execution
+if (process.argv[1]?.endsWith("generate-api-routes.ts")) {
+	console.log("🌸 Blumen API Route Generator");
+	console.log(`   Scanning: ${API_DIR}`);
+
+	const routes = generateAPIRoutes();
+
+	if (routes.length === 0) {
+		console.log("   No API routes found.");
+	} else {
+		console.log(`   Found ${routes.length} API route(s):`);
+		for (const r of routes) {
+			console.log(`     ${r.methods.join("|").padEnd(20)} ${r.route}`);
+		}
+	}
+
+	console.log(`   ✅ Written: ${path.relative(process.cwd(), API_OUTPUT)}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "blumenjs",
-	"version": "0.2.3",
+	"version": "0.2.5",
 	"description": "The React framework powered by Go. Lightning-fast SSR with the DX you deserve.",
 	"type": "module",
 	"bin": {