@funstack/static 0.0.5 → 0.0.6

package/README.md

@@ -37,7 +37,7 @@ export default defineConfig({
 
 ## Documentation
 
-For detailed API documentation and guides, visit the **[Documentation](https://uhyo.github.io/funstack-static/)**.
+For detailed API documentation and guides, visit the **[Documentation](https://static.funstack.work/)**.
 
 ### :robot: FUNSTACK Static Skill
 

package/dist/build/buildApp.mjs

@@ -3,6 +3,7 @@ import { getRscPayloadPath, rscPayloadPlaceholder } from "./rscPath.mjs";
 import { drainStream } from "../util/drainStream.mjs";
 import { computeContentHash } from "./contentHash.mjs";
 import { processRscComponents } from "./rscProcessor.mjs";
+import { checkDuplicatePaths, validateEntryPath } from "./validateEntryPath.mjs";
 import path from "node:path";
 import { mkdir, writeFile } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
@@ -12,16 +13,44 @@ async function buildApp(builder, context) {
 	const { config } = builder;
 	const entry = await import(pathToFileURL(path.join(config.environments.rsc.build.outDir, "index.js")).href);
 	const baseDir = config.environments.client.build.outDir;
-	const { html, appRsc, deferRegistry } = await entry.build();
+	const base = normalizeBase(config.base);
+	const { entries, deferRegistry } = await entry.build();
+	const paths = [];
+	for (const result of entries) {
+		const error = validateEntryPath(result.path);
+		if (error) throw new Error(error);
+		paths.push(result.path);
+	}
+	const dupError = checkDuplicatePaths(paths);
+	if (dupError) throw new Error(dupError);
+	const dummyStream = new ReadableStream({ start(controller) {
+		controller.close();
+	} });
+	const { components, idMapping } = await processRscComponents(deferRegistry.loadAll(), dummyStream, context);
+	for (const result of entries) await buildSingleEntry(result, idMapping, baseDir, base, context);
+	for (const { finalId, finalContent, name } of components) await writeFileNormal(path.join(baseDir, getModulePathFor(finalId).replace(/^\//, "")), finalContent, context, name);
+}
+function normalizeBase(base) {
+	const normalized = base.endsWith("/") ? base.slice(0, -1) : base;
+	return normalized === "/" ? "" : normalized;
+}
+/**
+* Replaces temporary IDs with final hashed IDs in content.
+*/
+function replaceIdsInContent(content, idMapping) {
+	let result = content;
+	for (const [oldId, newId] of idMapping) if (oldId !== newId) result = result.replaceAll(oldId, newId);
+	return result;
+}
+async function buildSingleEntry(result, idMapping, baseDir, base, context) {
+	const { path: entryPath, html, appRsc } = result;
 	const htmlContent = await drainStream(html);
-	const { components, appRscContent } = await processRscComponents(deferRegistry.loadAll(), appRsc, context);
+	const appRscContent = replaceIdsInContent(await drainStream(appRsc), idMapping);
 	const mainPayloadHash = await computeContentHash(appRscContent);
-	const base = config.base.endsWith("/") ? config.base.slice(0, -1) : config.base;
-	const mainPayloadPath = base === "/" ? getRscPayloadPath(mainPayloadHash) : base + getRscPayloadPath(mainPayloadHash);
+	const mainPayloadPath = base === "" ? getRscPayloadPath(mainPayloadHash) : base + getRscPayloadPath(mainPayloadHash);
 	const finalHtmlContent = htmlContent.replaceAll(rscPayloadPlaceholder, mainPayloadPath);
-	await writeFileNormal(path.join(baseDir, "index.html"), finalHtmlContent, context);
+	await writeFileNormal(path.join(baseDir, entryPath), finalHtmlContent, context);
 	await writeFileNormal(path.join(baseDir, getRscPayloadPath(mainPayloadHash).replace(/^\//, "")), appRscContent, context);
-	for (const { finalId, finalContent, name } of components) await writeFileNormal(path.join(baseDir, getModulePathFor(finalId).replace(/^\//, "")), finalContent, context, name);
 }
 async function writeFileNormal(filePath, data, context, name) {
 	await mkdir(path.dirname(filePath), { recursive: true });

package/dist/build/buildApp.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"buildApp.mjs","names":[],"sources":["../../src/build/buildApp.ts"],"sourcesContent":["import { mkdir, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport type { ViteBuilder, MinimalPluginContextWithoutEnvironment } from \"vite\";\nimport { rscPayloadPlaceholder, getRscPayloadPath } from \"./rscPath\";\nimport { getModulePathFor } from \"../rsc/rscModule\";\nimport { processRscComponents } from \"./rscProcessor\";\nimport { computeContentHash } from \"./contentHash\";\nimport { drainStream } from \"../util/drainStream\";\n\nexport async function buildApp(\n  builder: ViteBuilder,\n  context: MinimalPluginContextWithoutEnvironment,\n) {\n  const { config } = builder;\n  // import server entry\n  const entryPath = path.join(config.environments.rsc.build.outDir, \"index.js\");\n  const entry: typeof import(\"../rsc/entry\") = await import(\n    pathToFileURL(entryPath).href\n  );\n\n  // render rsc and html\n  const baseDir = config.environments.client.build.outDir;\n  const { html, appRsc, deferRegistry } = await entry.build();\n\n  // Drain HTML stream to string (needed for placeholder replacement later)\n  const htmlContent = await drainStream(html);\n\n  // Process RSC components with content-based hashes for deterministic file names\n  const { components, appRscContent } = await processRscComponents(\n    deferRegistry.loadAll(),\n    appRsc,\n    context,\n  );\n\n  // Compute hash for main RSC payload and apply base path\n  const mainPayloadHash = await computeContentHash(appRscContent);\n  const base = config.base.endsWith(\"/\")\n    ? config.base.slice(0, -1)\n    : config.base;\n  const mainPayloadPath =\n    base === \"/\"\n      ? getRscPayloadPath(mainPayloadHash)\n      : base + getRscPayloadPath(mainPayloadHash);\n\n  // Replace placeholder with final hashed path (including base path)\n  const finalHtmlContent = htmlContent.replaceAll(\n    rscPayloadPlaceholder,\n    mainPayloadPath,\n  );\n\n  // Write HTML with replaced path\n  await writeFileNormal(\n    path.join(baseDir, \"index.html\"),\n    finalHtmlContent,\n    context,\n  );\n\n  // Write main RSC payload with hashed filename\n  await writeFileNormal(\n    path.join(baseDir, getRscPayloadPath(mainPayloadHash).replace(/^\\//, \"\")),\n    appRscContent,\n    context,\n  );\n\n  // Write processed components with hash-based IDs\n  for (const { finalId, finalContent, name } of components) {\n    const filePath = path.join(\n      baseDir,\n      getModulePathFor(finalId).replace(/^\\//, \"\"),\n    );\n    await writeFileNormal(filePath, finalContent, context, name);\n  }\n}\n\nasync function writeFileNormal(\n  filePath: string,\n  data: string,\n  context: MinimalPluginContextWithoutEnvironment,\n  name?: string,\n) {\n  await mkdir(path.dirname(filePath), { recursive: true });\n  const nameInfo = name ? ` (${name})` : \"\";\n  context.info(`[funstack] Writing ${filePath}${nameInfo}`);\n  await writeFile(filePath, data);\n}\n"],"mappings":";;;;;;;;;;AAUA,eAAsB,SACpB,SACA,SACA;CACA,MAAM,EAAE,WAAW;CAGnB,MAAM,QAAuC,MAAM,OACjD,cAFgB,KAAK,KAAK,OAAO,aAAa,IAAI,MAAM,QAAQ,WAAW,CAEnD,CAAC;CAI3B,MAAM,UAAU,OAAO,aAAa,OAAO,MAAM;CACjD,MAAM,EAAE,MAAM,QAAQ,kBAAkB,MAAM,MAAM,OAAO;CAG3D,MAAM,cAAc,MAAM,YAAY,KAAK;CAG3C,MAAM,EAAE,YAAY,kBAAkB,MAAM,qBAC1C,cAAc,SAAS,EACvB,QACA,QACD;CAGD,MAAM,kBAAkB,MAAM,mBAAmB,cAAc;CAC/D,MAAM,OAAO,OAAO,KAAK,SAAS,IAAI,GAClC,OAAO,KAAK,MAAM,GAAG,GAAG,GACxB,OAAO;CACX,MAAM,kBACJ,SAAS,MACL,kBAAkB,gBAAgB,GAClC,OAAO,kBAAkB,gBAAgB;CAG/C,MAAM,mBAAmB,YAAY,WACnC,uBACA,gBACD;AAGD,OAAM,gBACJ,KAAK,KAAK,SAAS,aAAa,EAChC,kBACA,QACD;AAGD,OAAM,gBACJ,KAAK,KAAK,SAAS,kBAAkB,gBAAgB,CAAC,QAAQ,OAAO,GAAG,CAAC,EACzE,eACA,QACD;AAGD,MAAK,MAAM,EAAE,SAAS,cAAc,UAAU,WAK5C,OAAM,gBAJW,KAAK,KACpB,SACA,iBAAiB,QAAQ,CAAC,QAAQ,OAAO,GAAG,CAC7C,EAC+B,cAAc,SAAS,KAAK;;AAIhE,eAAe,gBACb,UACA,MACA,SACA,MACA;AACA,OAAM,MAAM,KAAK,QAAQ,SAAS,EAAE,EAAE,WAAW,MAAM,CAAC;CACxD,MAAM,WAAW,OAAO,KAAK,KAAK,KAAK;AACvC,SAAQ,KAAK,sBAAsB,WAAW,WAAW;AACzD,OAAM,UAAU,UAAU,KAAK"}
+{"version":3,"file":"buildApp.mjs","names":[],"sources":["../../src/build/buildApp.ts"],"sourcesContent":["import { mkdir, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport type { ViteBuilder, MinimalPluginContextWithoutEnvironment } from \"vite\";\nimport { rscPayloadPlaceholder, getRscPayloadPath } from \"./rscPath\";\nimport { getModulePathFor } from \"../rsc/rscModule\";\nimport { processRscComponents } from \"./rscProcessor\";\nimport { computeContentHash } from \"./contentHash\";\nimport { drainStream } from \"../util/drainStream\";\nimport { validateEntryPath, checkDuplicatePaths } from \"./validateEntryPath\";\nimport type { EntryBuildResult } from \"../rsc/entry\";\n\nexport async function buildApp(\n  builder: ViteBuilder,\n  context: MinimalPluginContextWithoutEnvironment,\n) {\n  const { config } = builder;\n  // import server entry\n  const entryPath = path.join(config.environments.rsc.build.outDir, \"index.js\");\n  const entry: typeof import(\"../rsc/entry\") = await import(\n    pathToFileURL(entryPath).href\n  );\n\n  const baseDir = config.environments.client.build.outDir;\n  const base = normalizeBase(config.base);\n\n  const { entries, deferRegistry } = await entry.build();\n\n  // Validate all entry paths\n  const paths: string[] = [];\n  for (const result of entries) {\n    const error = validateEntryPath(result.path);\n    if (error) {\n      throw new Error(error);\n    }\n    paths.push(result.path);\n  }\n  const dupError = checkDuplicatePaths(paths);\n  if (dupError) {\n    throw new Error(dupError);\n  }\n\n  // Process all deferred components once across all entries.\n  // We pass a dummy empty stream since we handle per-entry RSC payloads separately.\n  const dummyStream = new ReadableStream<Uint8Array>({\n    start(controller) {\n      controller.close();\n    },\n  });\n  const { components, idMapping } = await processRscComponents(\n    deferRegistry.loadAll(),\n    dummyStream,\n    context,\n  );\n\n  // Write each entry's HTML and RSC payload\n  for (const result of entries) {\n    await buildSingleEntry(result, idMapping, baseDir, base, context);\n  }\n\n  // Write all deferred component payloads\n  for (const { finalId, finalContent, name } of components) {\n    const filePath = path.join(\n      baseDir,\n      getModulePathFor(finalId).replace(/^\\//, \"\"),\n    );\n    await writeFileNormal(filePath, finalContent, context, name);\n  }\n}\n\nfunction normalizeBase(base: string): string {\n  const normalized = base.endsWith(\"/\") ? base.slice(0, -1) : base;\n  return normalized === \"/\" ? \"\" : normalized;\n}\n\n/**\n * Replaces temporary IDs with final hashed IDs in content.\n */\nfunction replaceIdsInContent(\n  content: string,\n  idMapping: Map<string, string>,\n): string {\n  let result = content;\n  for (const [oldId, newId] of idMapping) {\n    if (oldId !== newId) {\n      result = result.replaceAll(oldId, newId);\n    }\n  }\n  return result;\n}\n\nasync function buildSingleEntry(\n  result: EntryBuildResult,\n  idMapping: Map<string, string>,\n  baseDir: string,\n  base: string,\n  context: MinimalPluginContextWithoutEnvironment,\n) {\n  const { path: entryPath, html, appRsc } = result;\n\n  // Drain HTML stream to string\n  const htmlContent = await drainStream(html);\n\n  // Drain and process RSC payload: replace temp IDs with final hashed IDs\n  const rawAppRscContent = await drainStream(appRsc);\n  const appRscContent = replaceIdsInContent(rawAppRscContent, idMapping);\n\n  // Compute hash for this entry's RSC payload\n  const mainPayloadHash = await computeContentHash(appRscContent);\n  const mainPayloadPath =\n    base === \"\"\n      ? getRscPayloadPath(mainPayloadHash)\n      : base + getRscPayloadPath(mainPayloadHash);\n\n  // Replace placeholder with final hashed path\n  const finalHtmlContent = htmlContent.replaceAll(\n    rscPayloadPlaceholder,\n    mainPayloadPath,\n  );\n\n  // entryPath is already a file name (e.g. \"index.html\", \"about.html\")\n  await writeFileNormal(\n    path.join(baseDir, entryPath),\n    finalHtmlContent,\n    context,\n  );\n\n  // Write RSC payload with hashed filename\n  await writeFileNormal(\n    path.join(baseDir, getRscPayloadPath(mainPayloadHash).replace(/^\\//, \"\")),\n    appRscContent,\n    context,\n  );\n}\n\nasync function writeFileNormal(\n  filePath: string,\n  data: string,\n  context: MinimalPluginContextWithoutEnvironment,\n  name?: string,\n) {\n  await mkdir(path.dirname(filePath), { recursive: true });\n  const nameInfo = name ? ` (${name})` : \"\";\n  context.info(`[funstack] Writing ${filePath}${nameInfo}`);\n  await writeFile(filePath, data);\n}\n"],"mappings":";;;;;;;;;;;AAYA,eAAsB,SACpB,SACA,SACA;CACA,MAAM,EAAE,WAAW;CAGnB,MAAM,QAAuC,MAAM,OACjD,cAFgB,KAAK,KAAK,OAAO,aAAa,IAAI,MAAM,QAAQ,WAAW,CAEnD,CAAC;CAG3B,MAAM,UAAU,OAAO,aAAa,OAAO,MAAM;CACjD,MAAM,OAAO,cAAc,OAAO,KAAK;CAEvC,MAAM,EAAE,SAAS,kBAAkB,MAAM,MAAM,OAAO;CAGtD,MAAM,QAAkB,EAAE;AAC1B,MAAK,MAAM,UAAU,SAAS;EAC5B,MAAM,QAAQ,kBAAkB,OAAO,KAAK;AAC5C,MAAI,MACF,OAAM,IAAI,MAAM,MAAM;AAExB,QAAM,KAAK,OAAO,KAAK;;CAEzB,MAAM,WAAW,oBAAoB,MAAM;AAC3C,KAAI,SACF,OAAM,IAAI,MAAM,SAAS;CAK3B,MAAM,cAAc,IAAI,eAA2B,EACjD,MAAM,YAAY;AAChB,aAAW,OAAO;IAErB,CAAC;CACF,MAAM,EAAE,YAAY,cAAc,MAAM,qBACtC,cAAc,SAAS,EACvB,aACA,QACD;AAGD,MAAK,MAAM,UAAU,QACnB,OAAM,iBAAiB,QAAQ,WAAW,SAAS,MAAM,QAAQ;AAInE,MAAK,MAAM,EAAE,SAAS,cAAc,UAAU,WAK5C,OAAM,gBAJW,KAAK,KACpB,SACA,iBAAiB,QAAQ,CAAC,QAAQ,OAAO,GAAG,CAC7C,EAC+B,cAAc,SAAS,KAAK;;AAIhE,SAAS,cAAc,MAAsB;CAC3C,MAAM,aAAa,KAAK,SAAS,IAAI,GAAG,KAAK,MAAM,GAAG,GAAG,GAAG;AAC5D,QAAO,eAAe,MAAM,KAAK;;;;;AAMnC,SAAS,oBACP,SACA,WACQ;CACR,IAAI,SAAS;AACb,MAAK,MAAM,CAAC,OAAO,UAAU,UAC3B,KAAI,UAAU,MACZ,UAAS,OAAO,WAAW,OAAO,MAAM;AAG5C,QAAO;;AAGT,eAAe,iBACb,QACA,WACA,SACA,MACA,SACA;CACA,MAAM,EAAE,MAAM,WAAW,MAAM,WAAW;CAG1C,MAAM,cAAc,MAAM,YAAY,KAAK;CAI3C,MAAM,gBAAgB,oBADG,MAAM,YAAY,OAAO,EACU,UAAU;CAGtE,MAAM,kBAAkB,MAAM,mBAAmB,cAAc;CAC/D,MAAM,kBACJ,SAAS,KACL,kBAAkB,gBAAgB,GAClC,OAAO,kBAAkB,gBAAgB;CAG/C,MAAM,mBAAmB,YAAY,WACnC,uBACA,gBACD;AAGD,OAAM,gBACJ,KAAK,KAAK,SAAS,UAAU,EAC7B,kBACA,QACD;AAGD,OAAM,gBACJ,KAAK,KAAK,SAAS,kBAAkB,gBAAgB,CAAC,QAAQ,OAAO,GAAG,CAAC,EACzE,eACA,QACD;;AAGH,eAAe,gBACb,UACA,MACA,SACA,MACA;AACA,OAAM,MAAM,KAAK,QAAQ,SAAS,EAAE,EAAE,WAAW,MAAM,CAAC;CACxD,MAAM,WAAW,OAAO,KAAK,KAAK,KAAK;AACvC,SAAQ,KAAK,sBAAsB,WAAW,WAAW;AACzD,OAAM,UAAU,UAAU,KAAK"}

package/dist/build/validateEntryPath.mjs

@@ -0,0 +1,28 @@
+//#region src/build/validateEntryPath.ts
+/**
+* Validates an entry path string.
+* - Must end with ".html"
+* - Must not start with "/"
+*
+* @returns An error message if invalid, or undefined if valid.
+*/
+function validateEntryPath(entryPath) {
+	if (entryPath.startsWith("/")) return `Entry path must not start with "/": "${entryPath}". Paths are relative to the output directory.`;
+	if (!entryPath.endsWith(".html")) return `Entry path must end with ".html": "${entryPath}"`;
+}
+/**
+* Checks an array of entry paths for duplicates.
+*
+* @returns An error message if duplicates found, or undefined if all unique.
+*/
+function checkDuplicatePaths(paths) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const p of paths) {
+		if (seen.has(p)) return `Duplicate entry path: "${p}"`;
+		seen.add(p);
+	}
+}
+
+//#endregion
+export { checkDuplicatePaths, validateEntryPath };
+//# sourceMappingURL=validateEntryPath.mjs.map

package/dist/build/validateEntryPath.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateEntryPath.mjs","names":[],"sources":["../../src/build/validateEntryPath.ts"],"sourcesContent":["/**\n * Validates an entry path string.\n * - Must end with \".html\"\n * - Must not start with \"/\"\n *\n * @returns An error message if invalid, or undefined if valid.\n */\nexport function validateEntryPath(entryPath: string): string | undefined {\n  if (entryPath.startsWith(\"/\")) {\n    return `Entry path must not start with \"/\": \"${entryPath}\". Paths are relative to the output directory.`;\n  }\n  if (!entryPath.endsWith(\".html\")) {\n    return `Entry path must end with \".html\": \"${entryPath}\"`;\n  }\n  return undefined;\n}\n\n/**\n * Checks an array of entry paths for duplicates.\n *\n * @returns An error message if duplicates found, or undefined if all unique.\n */\nexport function checkDuplicatePaths(paths: string[]): string | undefined {\n  const seen = new Set<string>();\n  for (const p of paths) {\n    if (seen.has(p)) {\n      return `Duplicate entry path: \"${p}\"`;\n    }\n    seen.add(p);\n  }\n  return undefined;\n}\n"],"mappings":";;;;;;;;AAOA,SAAgB,kBAAkB,WAAuC;AACvE,KAAI,UAAU,WAAW,IAAI,CAC3B,QAAO,wCAAwC,UAAU;AAE3D,KAAI,CAAC,UAAU,SAAS,QAAQ,CAC9B,QAAO,sCAAsC,UAAU;;;;;;;AAU3D,SAAgB,oBAAoB,OAAqC;CACvE,MAAM,uBAAO,IAAI,KAAa;AAC9B,MAAK,MAAM,KAAK,OAAO;AACrB,MAAI,KAAK,IAAI,EAAE,CACb,QAAO,0BAA0B,EAAE;AAErC,OAAK,IAAI,EAAE"}

package/dist/docs/GettingStarted.md

@@ -177,4 +177,5 @@ This registers the `funstack-static-knowledge` skill, which provides your AI ass
 
 - Learn about the [funstackStatic() Plugin API](/funstack-static/api/funstack-static) for configuration options
 - Understand [defer()](/funstack-static/api/defer) for Server Component chunk splitting
+- Build multi-page static sites with [Multiple Entrypoints](/funstack-static/learn/multiple-entrypoints)
 - Dive into [React Server Components](/funstack-static/learn/rsc) concepts

package/dist/docs/api/EntryDefinition.md

@@ -0,0 +1,139 @@
+# EntryDefinition
+
+The `EntryDefinition` type defines a single entry in a multi-page static site. Each entry produces one HTML file with its own RSC payload.
+
+## Import
+
+```typescript
+import type { EntryDefinition } from "@funstack/static/entries";
+```
+
+## Usage
+
+```tsx
+import type { EntryDefinition } from "@funstack/static/entries";
+
+export default function getEntries(): EntryDefinition[] {
+  return [
+    {
+      path: "index.html",
+      root: () => import("./root"),
+      app: () => import("./pages/Home"),
+    },
+    {
+      path: "about.html",
+      root: () => import("./root"),
+      app: () => import("./pages/About"),
+    },
+  ];
+}
+```
+
+## Type Definition
+
+```typescript
+interface EntryDefinition {
+  path: string;
+  root: MaybePromise<RootModule> | (() => MaybePromise<RootModule>);
+  app: ReactNode | MaybePromise<AppModule> | (() => MaybePromise<AppModule>);
+}
+
+type MaybePromise<T> = T | Promise<T>;
+type RootModule = {
+  default: React.ComponentType<{ children: React.ReactNode }>;
+};
+type AppModule = { default: React.ComponentType };
+```
+
+## Properties
+
+### path
+
+**Type:** `string`
+
+Output file path relative to the build output directory.
+
+- Must end with `.html`
+- Must not start with `/`
+- Duplicate paths cause a build error
+
+```typescript
+"index.html"; // -> /
+"about.html"; // -> /about
+"blog/post-1.html"; // -> /blog/post-1
+"blog/post-1/index.html"; // -> /blog/post-1/
+```
+
+### root
+
+**Type:** `MaybePromise<RootModule> | (() => MaybePromise<RootModule>)`
+
+The root component module. The module must have a `default` export of a component that accepts `{ children: React.ReactNode }`.
+
+```tsx
+// Lazy import (recommended)
+root: () => import("./root"),
+
+// Synchronous module object
+import Root from "./root";
+root: { default: Root },
+
+// Promise
+root: import("./root"),
+```
+
+Using lazy imports (`() => import(...)`) is recommended to keep memory usage low when generating many entries.
+
+### app
+
+**Type:** `ReactNode | MaybePromise<AppModule> | (() => MaybePromise<AppModule>)`
+
+The app content for this entry. Accepts three forms:
+
+**Module (sync or lazy)** -- the module must have a `default` export component:
+
+```tsx
+// Lazy import
+app: () => import("./pages/Home"),
+
+// Synchronous module
+import Home from "./pages/Home";
+app: { default: Home },
+```
+
+**React node** -- server component JSX rendered directly:
+
+```tsx
+app: <BlogPost slug="hello-world" content={content} />,
+```
+
+The React node form enables parameterized rendering for SSG, where each entry passes different data to the same component without needing a separate module file.
+
+## Return Type of getEntries
+
+The entries function can return either a synchronous iterable or an async iterable:
+
+```typescript
+type GetEntriesResult =
+  | Iterable<EntryDefinition>
+  | AsyncIterable<EntryDefinition>;
+```
+
+This allows returning arrays, generators, or async generators:
+
+```tsx
+// Array
+export default function getEntries(): EntryDefinition[] {
+  return [{ path: "index.html", root: ..., app: ... }];
+}
+
+// Async generator
+export default async function* getEntries() {
+  yield { path: "index.html", root: ..., app: ... };
+}
+```
+
+## See Also
+
+- [Multiple Entrypoints](/funstack-static/learn/multiple-entrypoints) - Guide and examples
+- [funstackStatic()](/funstack-static/api/funstack-static) - Plugin configuration

package/dist/docs/api/FunstackStatic.md

@@ -10,6 +10,12 @@ import funstackStatic from "@funstack/static";
 
 ## Usage
 
+There are two configuration modes: **single-entry** (one HTML page) and **multiple entries** (multiple HTML pages).
+
+### Single-Entry Mode
+
+Use `root` and `app` to produce a single `index.html`:
+
 ```typescript
 // vite.config.ts
 import funstackStatic from "@funstack/static";
@@ -25,14 +31,41 @@ export default defineConfig({
 });
 ```
 
+### Multiple Entries Mode
+
+Use `entries` to produce multiple HTML pages from a single project:
+
+```typescript
+// vite.config.ts
+import funstackStatic from "@funstack/static";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    funstackStatic({
+      entries: "./src/entries.tsx",
+    }),
+    react(),
+  ],
+});
+```
+
+See [Multiple Entrypoints](/funstack-static/learn/multiple-entrypoints) for a full guide.
+
 ## Options
 
-### root (required)
+The plugin accepts either `root` + `app` (single-entry) or `entries` (multiple entries). These two modes are mutually exclusive.
+
+### root
 
 **Type:** `string`
+**Required in:** single-entry mode
 
 Path to the root component file. This component wraps your entire application and defines the HTML document structure (`<html>`, `<head>`, `<body>`).
 
+Cannot be used together with `entries`.
+
 ```typescript
 funstackStatic({
   root: "./src/root.tsx",
@@ -57,12 +90,15 @@ export default function Root({ children }: { children: React.ReactNode }) {
 }
 ```
 
-### app (required)
+### app
 
 **Type:** `string`
+**Required in:** single-entry mode
 
 Path to the app component file. This component defines your application's content.
 
+Cannot be used together with `entries`.
+
 ```typescript
 funstackStatic({
   root: "./src/root.tsx",
@@ -85,6 +121,45 @@ export default function App() {
 
 **Note:** if your app has multiple pages, you can use a routing library here just like in a traditional SPA.
 
+### entries
+
+**Type:** `string`
+**Required in:** multiple entries mode
+
+Path to an entries module that exports a function returning entry definitions. Each entry produces its own HTML file.
+
+Cannot be used together with `root` or `app`.
+
+```typescript
+funstackStatic({
+  entries: "./src/entries.tsx",
+});
+```
+
+The entries module must default-export a function that returns entry definitions:
+
+```tsx
+// src/entries.tsx
+import type { EntryDefinition } from "@funstack/static/entries";
+
+export default function getEntries(): EntryDefinition[] {
+  return [
+    {
+      path: "index.html",
+      root: () => import("./root"),
+      app: () => import("./pages/Home"),
+    },
+    {
+      path: "about.html",
+      root: () => import("./root"),
+      app: () => import("./pages/About"),
+    },
+  ];
+}
+```
+
+See [Multiple Entrypoints](/funstack-static/learn/multiple-entrypoints) for details on the `EntryDefinition` type and advanced usage patterns like async generators.
+
 ### publicOutDir (optional)
 
 **Type:** `string`
@@ -153,6 +228,8 @@ Sentry.init({
 
 ## Full Example
 
+### Single-Entry
+
 ```typescript
 // vite.config.ts
 import { funstackStatic } from "@funstack/static";
@@ -169,6 +246,24 @@ export default defineConfig({
 });
 ```
 
+### Multiple Entries
+
+```typescript
+// vite.config.ts
+import funstackStatic from "@funstack/static";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    funstackStatic({
+      entries: "./src/entries.tsx",
+    }),
+    react(),
+  ],
+});
+```
+
 ## Vite Commands
 
 You can use the same Vite commands you would use in a normal Vite project:
@@ -180,5 +275,6 @@ You can use the same Vite commands you would use in a normal Vite project:
 ## See Also
 
 - [Getting Started](/funstack-static/getting-started) - Quick start guide
+- [Multiple Entrypoints](/funstack-static/learn/multiple-entrypoints) - Multi-page static site generation
 - [defer()](/funstack-static/api/defer) - Deferred rendering for streaming
 - [React Server Components](/funstack-static/learn/rsc) - Understanding RSC

package/dist/docs/index.md

@@ -11,12 +11,15 @@ A Vite plugin for building static sites with React Server Components.
 ### API
 
 - [defer()](./api/Defer.md) - The `defer()` function enables deferred rendering for React Server Components, reducing initial data load.
+- [EntryDefinition](./api/EntryDefinition.md) - The `EntryDefinition` type defines a single entry in a multi-page static site. Each entry produces one HTML file with its own RSC payload.
 - [funstackStatic()](./api/FunstackStatic.md) - The `funstackStatic()` function is the main Vite plugin that enables React Server Components for building SPAs without a runtime server.
 
 ### Learn
 
+- [Prefetching with defer() and Activity](./learn/DeferAndActivity.md) - When using `defer()` to split RSC payloads, content is fetched on-demand as it renders. But what if you want to start fetching _before_ the user actually needs it? By combining `defer()` with React 19's `<Activity>` component, you can prefetch deferred payloads in the background so they're ready instantly when revealed.
 - [How It Works](./learn/HowItWorks.md) - FUNSTACK Static is a React framework that leverages React Server Components (RSC) to build a fully static Single Page Application. The result is a set of files that can be deployed to **any static file hosting service** - no server required at runtime.
 - [Using lazy() in Server Components](./learn/LazyServerComponents.md) - React's `lazy()` API is typically associated with client-side code splitting. However, it can also be used in server environments to reduce the initial response time of the development server by deferring the work needed to compute your application.
+- [Multiple Entrypoints](./learn/MultipleEntrypoints.md) - By default, FUNSTACK Static produces a single `index.html` from one `root` + `app` pair. The **multiple entries** feature lets you produce multiple HTML pages from a single project, targeting SSG (Static Site Generation) use cases where a site has distinct pages like `index.html`, `about.html`, and `blog/post-1.html`.
 - [Optimizing RSC Payloads](./learn/OptimizingPayloads.md) - FUNSTACK Static uses React Server Components (RSC) to pre-render your application at build time. By default, all content is bundled into a single RSC payload. This page explains how to split that payload into smaller chunks for better loading performance.
 - [React Server Components](./learn/RSC.md) - [React Server Components (RSC)](https://react.dev/reference/rsc/server-components) are a new paradigm for building React applications where components can run on the server (or at build time) rather than in the browser.
 - [Server-Side Rendering](./learn/SSR.md) - In FUNSTACK Static, **Server-Side Rendering (SSR)** means a build-time process that pre-renders your React components (including client components) to HTML. This can make the initial paint faster.

package/dist/docs/learn/DeferAndActivity.md

@@ -0,0 +1,176 @@
+# Prefetching with defer() and Activity
+
+When using `defer()` to split RSC payloads, content is fetched on-demand as it renders. But what if you want to start fetching _before_ the user actually needs it? By combining `defer()` with React 19's `<Activity>` component, you can prefetch deferred payloads in the background so they're ready instantly when revealed.
+
+## What Is Activity?
+
+`<Activity>` is a React 19 component that controls whether its children are visible or hidden:
+
+```tsx
+import { Activity } from "react";
+
+<Activity mode="visible">
+  <Panel />   {/* Rendered and visible */}
+</Activity>
+
+<Activity mode="hidden">
+  <Panel />   {/* Rendered but not visible in the DOM */}
+</Activity>
+```
+
+When `mode` is `"hidden"`, React still renders the children, but the output is hidden from the user and effects are not run until the `mode` becomes `"visible"`. The hidden content is rendered at a lower priority so it doesn't affect the performance of visible content. This is useful for keeping off-screen UI alive (preserving state, pre-warming components) without showing it.
+
+## How defer() and Activity Work Together
+
+Recall that `defer()` wraps a server component so its RSC payload is fetched separately from the main payload. The fetch starts when the deferred component renders on the client.
+
+The key insight is: **rendering under `<Activity mode="hidden">` still triggers the fetch**. The deferred component renders (starting the network request for its RSC payload), but the result isn't displayed. When you later switch the Activity to `"visible"`, the content appears immediately because the payload has already been downloaded.
+
+1. `<Activity mode="hidden">` renders defer()'ed content
+2. Client starts fetching the RSC payload in the background
+3. Payload arrives and is cached
+4. User triggers the UI to become visible
+5. `<Activity mode="visible">` — content shows instantly, no loading state
+
+## Example: Tabbed Interface
+
+Consider a tabbed interface where each tab contains heavy server-rendered content. Without prefetching, switching tabs shows a loading spinner while the payload is fetched. With `<Activity>`, you can prefetch all tabs on initial load.
+
+```tsx
+"use client";
+
+import { Activity, Suspense, useState } from "react";
+
+export function Tabs({
+  tabs,
+}: {
+  tabs: { label: string; content: React.ReactNode }[];
+}) {
+  const [activeIndex, setActiveIndex] = useState(0);
+
+  return (
+    <div>
+      <div role="tablist">
+        {tabs.map((tab, i) => (
+          <button
+            key={i}
+            role="tab"
+            aria-selected={i === activeIndex}
+            onClick={() => setActiveIndex(i)}
+          >
+            {tab.label}
+          </button>
+        ))}
+      </div>
+      {tabs.map((tab, i) => (
+        <Activity key={i} mode={i === activeIndex ? "visible" : "hidden"}>
+          <div role="tabpanel">
+            <Suspense fallback={<p>Loading...</p>}>{tab.content}</Suspense>
+          </div>
+        </Activity>
+      ))}
+    </div>
+  );
+}
+```
+
+On the server side, each tab's content is wrapped with `defer()`:
+
+```tsx
+import { defer } from "@funstack/static/server";
+import { Tabs } from "./Tabs";
+import Overview from "./tabs/Overview";
+import Specifications from "./tabs/Specifications";
+import Reviews from "./tabs/Reviews";
+
+function ProductPage() {
+  return (
+    <Tabs
+      tabs={[
+        {
+          label: "Overview",
+          content: defer(<Overview />, { name: "Overview" }),
+        },
+        {
+          label: "Specifications",
+          content: defer(<Specifications />, { name: "Specifications" }),
+        },
+        {
+          label: "Reviews",
+          content: defer(<Reviews />, { name: "Reviews" }),
+        },
+      ]}
+    />
+  );
+}
+```
+
+When this page loads:
+
+1. The active tab ("Overview") renders visibly and fetches its payload
+2. The hidden tabs ("Specifications", "Reviews") also render under `<Activity mode="hidden">`, triggering their payload fetches in the background
+3. When the user clicks "Specifications", it appears instantly — no spinner
+
+## Example: Collapsible Sections
+
+Another common pattern is pre-fetching content inside a collapsible section:
+
+```tsx
+"use client";
+
+import { Activity, Suspense, useState } from "react";
+
+export function Collapsible({
+  title,
+  children,
+}: {
+  title: string;
+  children: React.ReactNode;
+}) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div>
+      <button onClick={() => setIsOpen(!isOpen)}>{title}</button>
+      <Activity mode={isOpen ? "visible" : "hidden"}>
+        <Suspense fallback={<p>Loading...</p>}>{children}</Suspense>
+      </Activity>
+    </div>
+  );
+}
+```
+
+```tsx
+import { defer } from "@funstack/static/server";
+import { Collapsible } from "./Collapsible";
+import DetailedSpecs from "./DetailedSpecs";
+
+function Product() {
+  return (
+    <Collapsible title="Show detailed specifications">
+      {defer(<DetailedSpecs />, { name: "DetailedSpecs" })}
+    </Collapsible>
+  );
+}
+```
+
+Even though the section starts collapsed, `<Activity mode="hidden">` causes the deferred content to start fetching immediately. When the user expands the section, the content is already there.
+
+## When to Use This Pattern
+
+This pattern works best when:
+
+- **Content is likely to be needed soon** — If the user will probably view a tab or expand a section, prefetching eliminates the wait.
+- **Payload sizes are reasonable** — Prefetching multiple large payloads may waste bandwidth if the user never views them. Use judgment based on your typical user behavior.
+- **You want instant transitions** — Tabs, accordions, and similar reveal-based UI patterns benefit most from this approach.
+
+Avoid this pattern when:
+
+- **Content is rarely accessed** — Prefetching content most users never see wastes bandwidth.
+- **You have many deferred sections** — Prefetching dozens of payloads simultaneously may slow down the initial page load. Consider prefetching only the most likely targets.
+
+## See Also
+
+- [Optimizing RSC Payloads](/funstack-static/learn/optimizing-payloads) - Using `defer()` to split RSC payloads
+- [defer()](/funstack-static/api/defer) - API reference with full signature and technical details
+- [React Server Components](/funstack-static/learn/rsc) - Understanding RSC fundamentals