Add getStaticPaths API for dynamic SSG route generation

Replace prerender() with getStaticPaths() so route modules return param
objects instead of full paths, decoupling them from URL patterns.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: JoviDeCroock

docs/ARCHITECTURE.md

@@ -127,9 +127,9 @@ export function ErrorBoundary({ error }: ErrorBoundaryProps) {
   return <p>Something went wrong: {error.message}</p>;
 }
 
-// Build: enumerate paths for SSG/ISG prerendering (optional)
-export async function prerender(): Promise<string[]> {
-  return ["/dashboard"];
+// Build: enumerate params for SSG/ISG prerendering (optional)
+export function getStaticPaths(): RouteParams[] {
+  return [{ id: "1" }, { id: "2" }];
 }
 ```
 

docs/RENDERING_MODES.md

@@ -28,22 +28,26 @@ route — it's served as a static file.
 
 ### Dynamic SSG paths
 
-For routes with dynamic segments, export a `prerender` function:
+For routes with dynamic segments, export a `getStaticPaths` function that
+returns the params for each page to generate:
 
 ```typescript
 // src/routes/blog-post.tsx
-export async function prerender(): Promise<string[]> {
-  const posts = await getAllPosts();
-  return posts.map((p) => `/blog/${p.slug}`);
+import type { LoaderArgs, RouteParams } from "viact";
+
+export function getStaticPaths(): RouteParams[] {
+  const posts = getAllPosts();
+  return posts.map((p) => ({ slug: p.slug }));
 }
 
 export async function loader({ params }: LoaderArgs) {
   return { post: await getPost(params.slug) };
 }
 ```
 
-The build calls `prerender()` to enumerate all paths, then runs the loader
-and renderer for each. Output: `dist/client/blog/hello-world/index.html`, etc.
+The build calls `getStaticPaths()` to enumerate params, constructs full paths
+from the route pattern, then runs the loader and renderer for each.
+Output: `dist/client/blog/hello-world/index.html`, etc.
 
 Prerendering runs concurrently (default: 6 parallel renders).
 

e2e/node-build.test.ts

@@ -63,6 +63,17 @@ test("viact build emits a deployable Node server entry", async () => {
       "Viact starts with an explicit app manifest.",
     );
 
+    // Dynamic SSG routes should be prerendered as static HTML files
+    for (const id of ["1", "2", "3"]) {
+      const htmlPath = resolve(exampleDir, `dist/client/products/${id}/index.html`);
+      expect(existsSync(htmlPath)).toBe(true);
+
+      const productResponse = await fetch(`http://127.0.0.1:${port}/products/${id}`);
+      expect(productResponse.status).toBe(200);
+      const productHtml = await productResponse.text();
+      expect(productHtml).toContain("Price:");
+    }
+
     const apiResponse = await fetch(`http://127.0.0.1:${port}/api/health`);
     expect(apiResponse.status).toBe(200);
     await expect(apiResponse.json()).resolves.toEqual({ status: "ok" });

examples/basic/src/routes.ts

@@ -11,6 +11,10 @@ export const app = defineApp({
   routes: [
     group({ shell: "public" }, [
       route("/", "./routes/home.tsx", { id: "home", render: "ssg" }),
+      route("/products/:productId", "./routes/product.tsx", {
+        id: "product",
+        render: "ssg",
+      }),
       route("/pricing", "./routes/pricing.tsx", {
         id: "pricing",
         render: "isg",

examples/basic/src/routes/product.tsx

@@ -0,0 +1,26 @@
+import type { LoaderArgs, RouteComponentProps, RouteParams } from "viact";
+
+const PRODUCTS = [
+  { id: "1", name: "Widget", price: "$9.99" },
+  { id: "2", name: "Gadget", price: "$19.99" },
+  { id: "3", name: "Doohickey", price: "$4.99" },
+];
+
+export function getStaticPaths(): RouteParams[] {
+  return PRODUCTS.map((p) => ({ productId: p.id }));
+}
+
+export function loader({ params }: LoaderArgs) {
+  const product = PRODUCTS.find((p) => p.id === params.productId);
+  if (!product) throw new Error("Product not found");
+  return product;
+}
+
+export function Component({ data }: RouteComponentProps<typeof loader>) {
+  return (
+    <div>
+      <h1>{data.name}</h1>
+      <p>Price: {data.price}</p>
+    </div>
+  );
+}

examples/docs/src/routes/docs/recipes-i18n.md

@@ -224,11 +224,11 @@ export function LanguageSwitcher({ currentLocale }: { currentLocale: string }) {
 
 ## Tips
 
-- For **SSG** pages, use `prerender()` to generate a page per locale:
+- For **SSG** pages, use `getStaticPaths()` to generate a page per locale:
 
 ```ts
-export async function prerender() {
-  return ["/en/about", "/fr/about"];
+export function getStaticPaths(): RouteParams[] {
+  return [{ locale: "en" }, { locale: "fr" }];
 }
 ```
 

examples/docs/src/routes/docs/rendering.md

@@ -31,12 +31,12 @@ HTML is generated at build time. The loader runs once during the build, and the
 
 ### Dynamic SSG paths
 
-For routes with dynamic segments, export a `prerender` function to enumerate all paths:
+For routes with dynamic segments, export a `getStaticPaths` function that returns the params for each page:
 
 ```ts [src/routes/blog-post.tsx]
-export async function prerender(): Promise<string[]> {
-  const posts = await getAllPosts();
-  return posts.map(p => `/blog/${p.slug}`);
+export function getStaticPaths(): RouteParams[] {
+  const posts = getAllPosts();
+  return posts.map(p => ({ slug: p.slug }));
 }
 
 export async function loader({ params }: LoaderArgs) {
@@ -48,7 +48,7 @@ export function Component({ data }) {
 }
 ```
 
-The build calls `prerender()` to enumerate all paths, then runs the loader and renderer for each. Prerendering runs concurrently (default: 6 parallel renders).
+The build calls `getStaticPaths()` to enumerate params, constructs full paths from the route pattern, then runs the loader and renderer for each. Prerendering runs concurrently (default: 6 parallel renders).
 
 ---
 

packages/framework/src/app.ts

@@ -262,6 +262,17 @@ function normalizeRoutePath(path: string): string {
   return collapsed.length > 1 && collapsed.endsWith("/") ? collapsed.slice(0, -1) : collapsed;
 }
 
+export function buildPathFromSegments(segments: RouteSegment[], params: RouteParams): string {
+  const parts = segments.map((segment) => {
+    if (segment.type === "static") return segment.value;
+    if (segment.type === "param") return encodeURIComponent(params[segment.name] ?? "");
+    // catchall
+    return params["*"] ?? "";
+  });
+
+  return normalizeRoutePath("/" + parts.join("/"));
+}
+
 // ---------------------------------------------------------------------------
 // API Routes — file-based auto-discovery
 // ---------------------------------------------------------------------------

packages/framework/src/index.ts

@@ -1,4 +1,5 @@
 export {
+  buildPathFromSegments,
   defineApp,
   group,
   matchApiRoute,

packages/framework/src/runtime.ts

@@ -1183,17 +1183,19 @@ async function collectSSGPaths(
     return [route.path];
   }
 
-  // Dynamic route — must export prerender() to enumerate paths
+  // Dynamic route — must export getStaticPaths() to enumerate params
   const routeModule = await resolveRegistryModule<RouteModule>(registry?.routeModules, route.file);
 
-  if (!routeModule?.prerender) {
+  if (!routeModule?.getStaticPaths) {
     console.warn(
-      `  Warning: SSG route "${route.path}" has dynamic segments but no prerender() export, skipping.`,
+      `  Warning: SSG route "${route.path}" has dynamic segments but no getStaticPaths() export, skipping.`,
     );
     return [];
   }
 
-  return routeModule.prerender();
+  const { buildPathFromSegments } = await import("./app.ts");
+  const paramSets = await routeModule.getStaticPaths();
+  return paramSets.map((params) => buildPathFromSegments(route.segments, params));
 }
 
 async function readResponseBody(response: Response): Promise<unknown> {