@ilha/router 0.5.1 → 0.6.0

package/README.md

@@ -53,9 +53,9 @@ export default defineEventHandler((event) => {
 ### SSR + Client Hydration (recommended)
 
 ```ts
-// routes/[...].ts — Nitro handler
-import { pageRouter } from "ilha:pages";
-import { registry } from "ilha:registry";
+// routes/[...].ts — Nitro handler (SSR/prerender)
+import { pageRouter, registry } from "ilha:pages/server";
+import "ilha:loaders"; // ← wire server-only loaders
 
 export default defineEventHandler(async (event) => {
   const html = await pageRouter.renderHydratable(event.node.req.url ?? "/", registry);
@@ -67,8 +67,7 @@ export default defineEventHandler(async (event) => {
 
 ```ts
 // src/client.ts — browser entry
-import { pageRouter } from "ilha:pages";
-import { registry } from "ilha:registry";
+import { pageRouter, registry } from "ilha:pages/client";
 
 pageRouter.hydrate(registry);
 ```
@@ -916,18 +915,19 @@ export default ((error, route) =>
 
 ### Virtual modules
 
-The plugin exposes three virtual modules:
+The plugin exposes separate server and client virtual modules. **Always use the explicit `/server` or `/client` path** — they resolve to different generated files with different import strategies.
 
-| Module          | Export       | Description                                  |
-| --------------- | ------------ | -------------------------------------------- |
-| `ilha:pages`    | `pageRouter` | A `RouterBuilder` with all routes registered |
-| `ilha:registry` | `registry`   | `Record<string, Island>` for hydration       |
-| `ilha:loaders`  | —            | Side-effect import that wires server loaders |
+| Module              | Exports                  | Use for                                |
+| ------------------- | ------------------------ | -------------------------------------- |
+| `ilha:pages/server` | `pageRouter`, `registry` | SSR, prerender, Nitro handlers         |
+| `ilha:pages/client` | `pageRouter`, `registry` | Browser hydration entry                |
+| `ilha:loaders`      | —                        | Server-only side-effect: wires loaders |
+
+The server module imports page/layout/error modules **without** `?client` — raw imports so SSR sees full JSX including compound component render parts. The client module imports with `?client` which strips server-only `load` exports from the browser bundle.
 
 ```ts
-// routes/[...].ts — Nitro catch-all handler
-import { pageRouter } from "ilha:pages";
-import { registry } from "ilha:registry";
+// routes/[...].ts — SSR/prerender
+import { pageRouter, registry } from "ilha:pages/server";
 import "ilha:loaders"; // ← wire server loaders
 
 export default defineEventHandler(async (event) => {
@@ -940,18 +940,26 @@ export default defineEventHandler(async (event) => {
 
 ```ts
 // src/client.ts — browser entry
-import { pageRouter } from "ilha:pages";
-import { registry } from "ilha:registry";
+import { pageRouter, registry } from "ilha:pages/client";
 
 pageRouter.hydrate(registry);
 ```
 
+For `static` MPA mode:
+
+```ts
+// src/entry-client.ts — static/SSG browser entry
+import { pageRouter, registry } from "ilha:pages/client";
+
+pageRouter.hydrateStatic(registry);
+```
+
 ### Plugin options
 
 ```ts
 pages({
   dir: "src/pages", // pages directory (default: "src/pages")
-  generated: ".ilha/routes.ts", // generated file output (default: ".ilha/routes.ts")
+  outDir: ".ilha", // output directory for generated files (default: ".ilha")
   mode: "spa", // "spa" | "static" (default: "spa")
   interceptLinks: true, // only meaningful in spa mode (default: true)
 });

package/dist/{plugin-C-TVH3XD.js → plugin-CJBtP3fl.js}

@@ -138,44 +138,55 @@ function validateEntries(entries, pagesDir) {
 		else seenNames.set(entry.name, entry.file);
 	}
 }
-async function generate(pagesDir, outFile, options = {}) {
+function resolveGeneratedPaths(outDir) {
+	return {
+		serverFile: join(outDir, "pages.server.ts"),
+		clientFile: join(outDir, "pages.client.ts"),
+		loadersFile: join(outDir, "loaders.ts")
+	};
+}
+async function generate(pagesDir, outDir, options = {}) {
 	const mode = options.mode ?? "spa";
 	const interceptLinks = options.interceptLinks;
 	const isStatic = mode === "static";
 	const entries = sortEntries(await scanPages(pagesDir));
 	validateEntries(entries, pagesDir);
+	await mkdir(outDir, { recursive: true });
+	const { serverFile, clientFile, loadersFile } = resolveGeneratedPaths(outDir);
+	const serverChanged = await writeIfChanged(serverFile, buildServerFile(entries, serverFile));
+	const clientChanged = await writeIfChanged(clientFile, buildClientFile(entries, clientFile, {
+		isStatic,
+		interceptLinks
+	}));
+	if (!isStatic) await writeIfChanged(loadersFile, buildLoadersFile(entries, loadersFile, serverFile));
+	if (serverChanged || clientChanged) await generateTypes(outDir);
+}
+function buildServerFile(entries, serverFile) {
 	const rel = (abs) => {
-		const r = toPosix(relative(dirname(outFile), abs));
+		const r = toPosix(relative(dirname(serverFile), abs));
 		return r.startsWith(".") ? r : `./${r}`;
 	};
-	const imports = isStatic ? [`import type { Island } from "ilha";`] : [`import { router, wrapLayout, wrapError } from "@ilha/router";`, `import type { Island } from "ilha";`];
+	const imports = [`import { router, wrapLayout, wrapError } from "@ilha/router";`, `import type { Island } from "ilha";`];
 	const wrappedIslandLines = [];
 	const registryLines = [];
 	const routeLines = [];
-	const clientImport = (abs) => `${rel(abs)}?client`;
 	for (const [i, entry] of entries.entries()) {
-		const pageId = `_page${i}`;
-		imports.push(`import { default as ${pageId} } from ${JSON.stringify(clientImport(entry.file))};`);
-		if (!isStatic) {
-			for (const [j, l] of entry.layouts.entries()) imports.push(`import { default as _layout${i}_${j} } from ${JSON.stringify(clientImport(l))};`);
-			for (const [j, e] of entry.errors.entries()) imports.push(`import { default as _error${i}_${j} } from ${JSON.stringify(clientImport(e))};`);
-		}
-		let expr = pageId;
-		if (!isStatic) {
-			for (let j = entry.errors.length - 1; j >= 0; j--) expr = `wrapError(_error${i}_${j}, ${expr})`;
-			for (let j = entry.layouts.length - 1; j >= 0; j--) expr = `wrapLayout(_layout${i}_${j}, ${expr})`;
-		}
+		imports.push(`import { default as _page${i} } from ${JSON.stringify(rel(entry.file))};`);
+		for (const [j, l] of entry.layouts.entries()) imports.push(`import { default as _layout${i}_${j} } from ${JSON.stringify(rel(l))};`);
+		for (const [j, e] of entry.errors.entries()) imports.push(`import { default as _error${i}_${j} } from ${JSON.stringify(rel(e))};`);
+		let expr = `_page${i}`;
+		for (let j = entry.errors.length - 1; j >= 0; j--) expr = `wrapError(_error${i}_${j}, ${expr})`;
+		for (let j = entry.layouts.length - 1; j >= 0; j--) expr = `wrapLayout(_layout${i}_${j}, ${expr})`;
 		const wrappedId = `_wrapped${i}`;
 		wrappedIslandLines.push(`const ${wrappedId} = ${expr};`);
 		registryLines.push(`  ${JSON.stringify(entry.name)}: ${wrappedId}` + (i < entries.length - 1 ? "," : ""));
-		if (!isStatic) routeLines.push(`  .route(${JSON.stringify(entry.pattern)}, ${wrappedId})` + (entry.hasLoader || entry.loaderLayouts.length > 0 ? `.markLoader(${JSON.stringify(entry.pattern)})` : ""));
+		routeLines.push(`  .route(${JSON.stringify(entry.pattern)}, ${wrappedId})` + (entry.hasLoader || entry.loaderLayouts.length > 0 ? `.markLoader(${JSON.stringify(entry.pattern)})` : ""));
 	}
-	const code = isStatic ? [
+	return [
 		`// @generated by @ilha/router — do not edit`,
-		`// static mode: no route graph, no client navigation.`,
-		`// Import registry to hydrate islands; use pageRouter.hydrateStatic(registry).`,
+		`// Server module. Use for SSR and SSG/prerender.`,
+		`// Import via: import { pageRouter, registry } from "ilha:pages/server";`,
 		``,
-		`import { router as _router } from "@ilha/router";`,
 		...imports,
 		``,
 		...wrappedIslandLines,
@@ -184,9 +195,43 @@ async function generate(pagesDir, outFile, options = {}) {
 		...registryLines,
 		`};`,
 		``,
-		`export const pageRouter = _router({ mode: "static" });`
-	].join("\n") : [
+		`export const pageRouter = router()`,
+		...routeLines,
+		`  ;`
+	].join("\n");
+}
+function buildClientFile(entries, clientFile, opts) {
+	const { isStatic, interceptLinks } = opts;
+	const rel = (abs) => {
+		const r = toPosix(relative(dirname(clientFile), abs));
+		return r.startsWith(".") ? r : `./${r}`;
+	};
+	const clientImport = (abs) => `${rel(abs)}?client`;
+	const imports = isStatic ? [`import { router as _router } from "@ilha/router";`, `import type { Island } from "ilha";`] : [`import { router, wrapLayout, wrapError } from "@ilha/router";`, `import type { Island } from "ilha";`];
+	const wrappedIslandLines = [];
+	const registryLines = [];
+	const routeLines = [];
+	for (const [i, entry] of entries.entries()) {
+		imports.push(`import { default as _page${i} } from ${JSON.stringify(clientImport(entry.file))};`);
+		if (!isStatic) {
+			for (const [j, l] of entry.layouts.entries()) imports.push(`import { default as _layout${i}_${j} } from ${JSON.stringify(clientImport(l))};`);
+			for (const [j, e] of entry.errors.entries()) imports.push(`import { default as _error${i}_${j} } from ${JSON.stringify(clientImport(e))};`);
+		}
+		let expr = `_page${i}`;
+		if (!isStatic) {
+			for (let j = entry.errors.length - 1; j >= 0; j--) expr = `wrapError(_error${i}_${j}, ${expr})`;
+			for (let j = entry.layouts.length - 1; j >= 0; j--) expr = `wrapLayout(_layout${i}_${j}, ${expr})`;
+		}
+		const wrappedId = `_wrapped${i}`;
+		wrappedIslandLines.push(`const ${wrappedId} = ${expr};`);
+		registryLines.push(`  ${JSON.stringify(entry.name)}: ${wrappedId}` + (i < entries.length - 1 ? "," : ""));
+		if (!isStatic) routeLines.push(`  .route(${JSON.stringify(entry.pattern)}, ${wrappedId})` + (entry.hasLoader || entry.loaderLayouts.length > 0 ? `.markLoader(${JSON.stringify(entry.pattern)})` : ""));
+	}
+	const routerExpr = isStatic ? `_router({ mode: "static" })` : `router(${interceptLinks === false ? `{ interceptLinks: false }` : ""})`;
+	const lines = [
 		`// @generated by @ilha/router — do not edit`,
+		`// Client module. Use for browser hydration.`,
+		`// Import via: import { pageRouter, registry } from "ilha:pages/client";`,
 		``,
 		...imports,
 		``,
@@ -195,22 +240,13 @@ async function generate(pagesDir, outFile, options = {}) {
 		`export const registry: Record<string, Island<any, any>> = {`,
 		...registryLines,
 		`};`,
-		``,
-		`export const pageRouter = router(${interceptLinks === false ? `{ interceptLinks: false }` : ""})`,
-		...routeLines,
-		`  ;`
-	].join("\n");
-	await mkdir(dirname(outFile), { recursive: true });
-	const routesChanged = await writeIfChanged(outFile, code);
-	if (isStatic) {
-		if (routesChanged) await generateTypes(outFile);
-		return;
-	}
-	const loadersFile = join(dirname(outFile), "loaders.ts");
-	const loadersChanged = await writeIfChanged(loadersFile, buildLoadersFile(entries, loadersFile, outFile));
-	if (routesChanged || loadersChanged) await generateTypes(outFile);
+		``
+	];
+	if (isStatic) lines.push(`export const pageRouter = ${routerExpr};`);
+	else lines.push(`export const pageRouter = ${routerExpr}`, ...routeLines, `  ;`);
+	return lines.join("\n");
 }
-function buildLoadersFile(entries, loadersFile, routesFile) {
+function buildLoadersFile(entries, loadersFile, serverFile) {
 	const relFromLoaders = (abs) => {
 		const r = toPosix(relative(dirname(loadersFile), abs));
 		return r.startsWith(".") ? r : `./${r}`;
@@ -223,8 +259,8 @@ function buildLoadersFile(entries, loadersFile, routesFile) {
 		`export {};`,
 		``
 	].join("\n");
-	const routesRel = relFromLoaders(routesFile).replace(/\.tsx?$/, "");
-	const imports = [`import { pageRouter } from ${JSON.stringify(routesRel)};`];
+	const serverRel = relFromLoaders(serverFile).replace(/\.tsx?$/, "");
+	const imports = [`import { pageRouter } from ${JSON.stringify(serverRel)};`];
 	let needsComposeLoaders = false;
 	const attachLines = [];
 	for (const [i, entry] of withLoaders.entries()) {
@@ -263,17 +299,21 @@ async function writeIfChanged(file, content) {
 	await writeFile(file, content, "utf8");
 	return true;
 }
-async function generateTypes(outFile) {
-	await writeIfChanged(outFile.replace(/\.tsx?$/, ".d.ts"), [
+async function generateTypes(outDir) {
+	await writeIfChanged(join(outDir, "pages.d.ts"), [
 		`// @generated by @ilha/router — do not edit`,
 		``,
-		`declare module "ilha:pages" {`,
+		`declare module "ilha:pages/server" {`,
 		`  import type { RouterBuilder } from "@ilha/router";`,
+		`  import type { Island } from "ilha";`,
 		`  export const pageRouter: RouterBuilder;`,
+		`  export const registry: Record<string, Island<any, any>>;`,
 		`}`,
 		``,
-		`declare module "ilha:registry" {`,
+		`declare module "ilha:pages/client" {`,
+		`  import type { RouterBuilder } from "@ilha/router";`,
 		`  import type { Island } from "ilha";`,
+		`  export const pageRouter: RouterBuilder;`,
 		`  export const registry: Record<string, Island<any, any>>;`,
 		`}`,
 		``,
@@ -283,35 +323,40 @@ async function generateTypes(outFile) {
 		``
 	].join("\n"));
 }
-const RESOLVED_PAGES = "\0ilha:pages";
-const RESOLVED_REGISTRY = "\0ilha:registry";
+const RESOLVED_PAGES_SERVER = "\0ilha:pages/server";
+const RESOLVED_PAGES_CLIENT = "\0ilha:pages/client";
 const RESOLVED_LOADERS = "\0ilha:loaders";
 const RESOLVED_VIRTUAL_IDS = [
-	RESOLVED_PAGES,
-	RESOLVED_REGISTRY,
+	RESOLVED_PAGES_SERVER,
+	RESOLVED_PAGES_CLIENT,
 	RESOLVED_LOADERS
 ];
-/** Query suffix used on page/layout imports in the client-safe routes file. */
+/** Query suffix used on page/layout imports in the client file. */
 const CLIENT_QUERY = "?client";
 function resolvePluginPaths(root, options) {
 	const pagesDir = resolve(root, options.dir ?? "src/pages");
-	const outFile = resolve(root, options.generated ?? ".ilha/routes.ts");
+	const outDir = resolve(root, options.outDir ?? ".ilha");
+	const { serverFile, clientFile, loadersFile } = resolveGeneratedPaths(outDir);
 	return {
 		pagesDir,
-		outFile,
-		loadersFile: join(dirname(outFile), "loaders.ts")
+		outDir,
+		serverFile,
+		clientFile,
+		loadersFile
 	};
 }
 function createPagesPluginState(options) {
 	let pagesDir;
-	let outFile;
+	let outDir;
+	let serverFile;
+	let clientFile;
 	let loadersFile;
 	const setPaths = (root) => {
-		({pagesDir, outFile, loadersFile} = resolvePluginPaths(root, options));
+		({pagesDir, outDir, serverFile, clientFile, loadersFile} = resolvePluginPaths(root, options));
 	};
 	const regen = async () => {
 		try {
-			await generate(pagesDir, outFile, {
+			await generate(pagesDir, outDir, {
 				mode: options.mode,
 				interceptLinks: options.interceptLinks
 			});
@@ -329,8 +374,14 @@ function createPagesPluginState(options) {
 		get pagesDir() {
 			return pagesDir;
 		},
-		get outFile() {
-			return outFile;
+		get outDir() {
+			return outDir;
+		},
+		get serverFile() {
+			return serverFile;
+		},
+		get clientFile() {
+			return clientFile;
 		},
 		get loadersFile() {
 			return loadersFile;
@@ -346,22 +397,22 @@ async function regenFromPagesChange(state, file, shouldRegen) {
 	await state.regen();
 }
 function resolvePagesId(_state, id, importer) {
-	if (id === "ilha:pages") return RESOLVED_PAGES;
-	if (id === "ilha:registry") return RESOLVED_REGISTRY;
+	if (id === "ilha:pages/server") return RESOLVED_PAGES_SERVER;
+	if (id === "ilha:pages/client") return RESOLVED_PAGES_CLIENT;
 	if (id === "ilha:loaders") return RESOLVED_LOADERS;
 	if (id.endsWith("?client")) {
 		const bare = id.slice(0, -7);
-		return (importer ? resolve(dirname(importer.replace(/\?.*$/, "")), bare) : resolve(bare)) + CLIENT_QUERY;
+		return (importer ? resolve(importer.replace(/\?.*$/, ""), "..", bare) : resolve(bare)) + CLIENT_QUERY;
 	}
 }
 function loadPagesModule(state, id) {
-	if (id === "\0ilha:pages") {
-		const spec = state.outFile.replace(/\.tsx?$/, "");
-		return `export { pageRouter } from ${JSON.stringify(spec)};`;
+	if (id === "\0ilha:pages/server") {
+		const spec = state.serverFile.replace(/\.tsx?$/, "");
+		return `export { pageRouter, registry } from ${JSON.stringify(spec)};`;
 	}
-	if (id === "\0ilha:registry") {
-		const spec = state.outFile.replace(/\.tsx?$/, "");
-		return `export { registry } from ${JSON.stringify(spec)};`;
+	if (id === "\0ilha:pages/client") {
+		const spec = state.clientFile.replace(/\.tsx?$/, "");
+		return `export { pageRouter, registry } from ${JSON.stringify(spec)};`;
 	}
 	if (id === "\0ilha:loaders") {
 		const spec = state.loadersFile.replace(/\.tsx?$/, "");

package/dist/{plugin-BizQQLsn.d.ts → plugin-rauddckN.d.ts}

@@ -7,8 +7,8 @@ type PagesMode = "spa" | "static";
 interface IlhaPagesOptions {
   /** Directory containing page files. Default: `src/pages` */
   dir?: string;
-  /** Output path for the generated routes + registry file. Default: `.ilha/routes.ts` */
-  generated?: string;
+  /** Output directory for generated files. Default: `.ilha` */
+  outDir?: string;
   /**
    * File-system router navigation mode.
    * - `spa` — full client route graph with SSR/hydration and client navigation.

package/dist/rolldown.d.ts

@@ -1,5 +1,5 @@
 import { H as wrapLayout, V as wrapError, n as ErrorHandler, s as LayoutHandler, t as AppError, v as RouteSnapshot } from "./index-DZA_1KrG.js";
-import { n as ilhaPages, t as IlhaPagesOptions } from "./plugin-BizQQLsn.js";
+import { n as ilhaPages, t as IlhaPagesOptions } from "./plugin-rauddckN.js";
 import * as _$unplugin from "unplugin";
 
 //#region src/rolldown.d.ts

package/dist/rolldown.js

@@ -1,5 +1,5 @@
 import { C as wrapError, w as wrapLayout } from "./src-BP38YTMC.js";
-import { t as ilhaPages } from "./plugin-C-TVH3XD.js";
+import { t as ilhaPages } from "./plugin-CJBtP3fl.js";
 //#region src/rolldown.ts
 /** Rolldown plugin — use via `@ilha/router/rolldown`. */
 function pages(options = {}) {

package/dist/rspack.d.ts

@@ -1,5 +1,5 @@
 import { H as wrapLayout, V as wrapError, n as ErrorHandler, s as LayoutHandler, t as AppError, v as RouteSnapshot } from "./index-DZA_1KrG.js";
-import { n as ilhaPages, t as IlhaPagesOptions } from "./plugin-BizQQLsn.js";
+import { n as ilhaPages, t as IlhaPagesOptions } from "./plugin-rauddckN.js";
 import * as _$unplugin from "unplugin";
 
 //#region src/rspack.d.ts

package/dist/rspack.js

@@ -1,5 +1,5 @@
 import { C as wrapError, w as wrapLayout } from "./src-BP38YTMC.js";
-import { t as ilhaPages } from "./plugin-C-TVH3XD.js";
+import { t as ilhaPages } from "./plugin-CJBtP3fl.js";
 //#region src/rspack.ts
 /** Rspack plugin — use via `@ilha/router/rspack`. */
 function pages(options = {}) {

package/dist/vite.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="node" />
 import { H as wrapLayout, V as wrapError, n as ErrorHandler, s as LayoutHandler, t as AppError, v as RouteSnapshot } from "./index-DZA_1KrG.js";
-import { n as ilhaPages, t as IlhaPagesOptions } from "./plugin-BizQQLsn.js";
+import { n as ilhaPages, t as IlhaPagesOptions } from "./plugin-rauddckN.js";
 import * as fs from "node:fs";
 import * as http from "node:http";
 import { Agent, ClientRequest, ClientRequestArgs, OutgoingHttpHeaders } from "node:http";

package/dist/vite.js

@@ -1,5 +1,5 @@
 import { C as wrapError, w as wrapLayout } from "./src-BP38YTMC.js";
-import { t as ilhaPages } from "./plugin-C-TVH3XD.js";
+import { t as ilhaPages } from "./plugin-CJBtP3fl.js";
 //#region src/vite.ts
 /** Vite plugin — use via `@ilha/router/vite`. */
 function pages(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ilha/router",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "A tiny SPA router for Ilha",
   "license": "MIT",
   "author": "Ryuz <ryuzer@proton.me>",