@praxisjs/ssg 0.1.0

package/src/__tests__/resolve-sync.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect, vi } from "vitest";
+
+import type { ResolveFnOutput, ResolveHookContext } from "node:module";
+
+import { registerLoaderHook } from "../index";
+
+const { registerHooks } = vi.hoisted(() => ({
+  registerHooks: vi.fn(),
+}));
+
+vi.mock("node:module", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:module")>();
+  return { ...actual, registerHooks, register: vi.fn() };
+});
+
+const CONTEXT = {} as ResolveHookContext;
+
+function notFound(): never {
+  const err = new Error("not found") as Error & { code?: string };
+  err.code = "ERR_MODULE_NOT_FOUND";
+  throw err;
+}
+
+function ok(url: string): ResolveFnOutput {
+  return { url, shortCircuit: true } as ResolveFnOutput;
+}
+
+describe("resolveSync (registered via module.registerHooks())", () => {
+  registerLoaderHook();
+  const resolveSync = registerHooks.mock.calls[0][0].resolve as (
+    specifier: string,
+    context: ResolveHookContext,
+    nextResolve: (specifier: string, context?: Partial<ResolveHookContext>) => ResolveFnOutput,
+  ) => ResolveFnOutput;
+
+  it("registers exactly once via module.registerHooks()", () => {
+    expect(registerHooks).toHaveBeenCalledOnce();
+  });
+
+  it("returns nextResolve's result directly when it succeeds", () => {
+    const nextResolve = vi.fn(() => ok("file:///real.js"));
+    expect(resolveSync("./real", CONTEXT, nextResolve)).toEqual(ok("file:///real.js"));
+    expect(nextResolve).toHaveBeenCalledOnce();
+  });
+
+  it("rethrows without retrying for a bare (non-relative) specifier", () => {
+    const nextResolve = vi.fn(() => notFound());
+    expect(() => resolveSync("some-package", CONTEXT, nextResolve)).toThrow("not found");
+    expect(nextResolve).toHaveBeenCalledOnce();
+  });
+
+  it("rethrows without retrying when the error has no code", () => {
+    const nextResolve = vi.fn(() => {
+      throw new Error("weird failure");
+    });
+    expect(() => resolveSync("./router", CONTEXT, nextResolve)).toThrow("weird failure");
+    expect(nextResolve).toHaveBeenCalledOnce();
+  });
+
+  it("rethrows without retrying for a non-retryable error code", () => {
+    const nextResolve = vi.fn(() => {
+      const err = new Error("permission denied") as Error & { code?: string };
+      err.code = "EACCES";
+      throw err;
+    });
+    expect(() => resolveSync("./router", CONTEXT, nextResolve)).toThrow("permission denied");
+    expect(nextResolve).toHaveBeenCalledOnce();
+  });
+
+  it("retries with a .js suffix and returns it when that succeeds", () => {
+    const nextResolve = vi.fn((specifier: string) =>
+      specifier === "./router.js" ? ok("file:///router.js") : notFound(),
+    );
+    expect(resolveSync("./router", CONTEXT, nextResolve)).toEqual(ok("file:///router.js"));
+    expect(nextResolve).toHaveBeenCalledTimes(2);
+  });
+
+  it("falls back to /index.js when the .js candidate also fails", () => {
+    const nextResolve = vi.fn((specifier: string) =>
+      specifier === "./router/index.js" ? ok("file:///router/index.js") : notFound(),
+    );
+    expect(resolveSync("./router", CONTEXT, nextResolve)).toEqual(ok("file:///router/index.js"));
+    expect(nextResolve).toHaveBeenCalledTimes(3);
+  });
+
+  it("rethrows the original error when both retry candidates fail", () => {
+    const nextResolve = vi.fn(() => notFound());
+    expect(() => resolveSync("../router", CONTEXT, nextResolve)).toThrow("not found");
+    expect(nextResolve).toHaveBeenCalledTimes(3);
+  });
+});

package/src/__tests__/routes.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect } from "vitest";
+
+import type { RouteDefinition } from "@praxisjs/router";
+
+import { flattenRoutes, isStaticPath, pathToOutputFile, resolvePaths } from "../routes";
+
+const Noop = class {} as never;
+
+describe("flattenRoutes", () => {
+  it("flattens a flat route list unchanged", () => {
+    const routes: RouteDefinition[] = [
+      { path: "/", component: Noop },
+      { path: "/about", component: Noop },
+    ];
+    expect(flattenRoutes(routes).map((r) => r.fullPath)).toEqual(["/", "/about"]);
+  });
+
+  it("prefixes nested children with the parent path", () => {
+    const routes: RouteDefinition[] = [
+      {
+        path: "/blog",
+        component: Noop,
+        children: [
+          { path: "/", component: Noop },
+          { path: "/:slug", component: Noop },
+        ],
+      },
+    ];
+    expect(flattenRoutes(routes).map((r) => r.fullPath)).toEqual(["/blog", "/blog/", "/blog/:slug"]);
+  });
+
+  it("treats a root parent's prefix as empty, matching RouterInstance.addRoute", () => {
+    const routes: RouteDefinition[] = [
+      {
+        path: "/",
+        component: Noop,
+        children: [{ path: "/dashboard", component: Noop }],
+      },
+    ];
+    expect(flattenRoutes(routes).map((r) => r.fullPath)).toEqual(["/", "/dashboard"]);
+  });
+});
+
+describe("isStaticPath", () => {
+  it("treats plain paths as static", () => {
+    expect(isStaticPath("/about")).toBe(true);
+    expect(isStaticPath("/")).toBe(true);
+  });
+
+  it("treats :param segments as dynamic", () => {
+    expect(isStaticPath("/blog/:slug")).toBe(false);
+  });
+
+  it("treats optional :param? segments as dynamic", () => {
+    expect(isStaticPath("/users/:id?")).toBe(false);
+  });
+
+  it("treats ** catch-alls as dynamic", () => {
+    expect(isStaticPath("/docs/**")).toBe(false);
+  });
+});
+
+describe("resolvePaths", () => {
+  it("returns static paths as-is", async () => {
+    const routes: RouteDefinition[] = [
+      { path: "/", component: Noop },
+      { path: "/about", component: Noop },
+    ];
+    expect(await resolvePaths({ routes })).toEqual(["/", "/about"]);
+  });
+
+  it("expands a dynamic route via getStaticPaths", async () => {
+    const routes: RouteDefinition[] = [{ path: "/blog/:slug", component: Noop }];
+    const paths = await resolvePaths({
+      routes,
+      getStaticPaths: async () => ["/blog/hello", "/blog/world"],
+    });
+    expect(paths).toEqual(["/blog/hello", "/blog/world"]);
+  });
+
+  it("skips dynamic routes with no getStaticPaths", async () => {
+    const routes: RouteDefinition[] = [
+      { path: "/", component: Noop },
+      { path: "/blog/:slug", component: Noop },
+    ];
+    expect(await resolvePaths({ routes })).toEqual(["/"]);
+  });
+
+  it("passes the route and its full path pattern to getStaticPaths", async () => {
+    const target: RouteDefinition = { path: "/blog/:slug", component: Noop };
+    const routes: RouteDefinition[] = [target];
+    let seen: [RouteDefinition, string] | undefined;
+    await resolvePaths({
+      routes,
+      getStaticPaths: async (route, fullPath) => {
+        seen = [route, fullPath];
+        return [];
+      },
+    });
+    expect(seen).toEqual([target, "/blog/:slug"]);
+  });
+
+  it("de-duplicates paths across routes", async () => {
+    const routes: RouteDefinition[] = [
+      { path: "/blog/:slug", component: Noop },
+      { path: "/other/:slug", component: Noop },
+    ];
+    const paths = await resolvePaths({
+      routes,
+      getStaticPaths: async () => ["/shared"],
+    });
+    expect(paths).toEqual(["/shared"]);
+  });
+
+  it("expands a dynamic route via its own colocated getStaticPaths, with no global fallback needed", async () => {
+    const routes: RouteDefinition[] = [
+      { path: "/blog/:slug", component: Noop, getStaticPaths: async () => ["/blog/hello", "/blog/world"] } as RouteDefinition,
+    ];
+    expect(await resolvePaths({ routes })).toEqual(["/blog/hello", "/blog/world"]);
+  });
+
+  it("passes the route's own full path to its colocated getStaticPaths", async () => {
+    let seen: string | undefined;
+    const routes: RouteDefinition[] = [
+      {
+        path: "/blog/:slug",
+        component: Noop,
+        getStaticPaths: async (fullPath: string) => {
+          seen = fullPath;
+          return [];
+        },
+      } as RouteDefinition,
+    ];
+    await resolvePaths({ routes });
+    expect(seen).toBe("/blog/:slug");
+  });
+
+  it("prefers a route's own getStaticPaths over the global fallback", async () => {
+    const routes: RouteDefinition[] = [
+      { path: "/blog/:slug", component: Noop, getStaticPaths: async () => ["/blog/own"] } as RouteDefinition,
+    ];
+    const paths = await resolvePaths({
+      routes,
+      getStaticPaths: async () => ["/blog/global"],
+    });
+    expect(paths).toEqual(["/blog/own"]);
+  });
+
+  it("falls back to the global getStaticPaths for routes with no colocated one, alongside routes that have their own", async () => {
+    const routes: RouteDefinition[] = [
+      { path: "/blog/:slug", component: Noop, getStaticPaths: async () => ["/blog/own"] } as RouteDefinition,
+      { path: "/other/:slug", component: Noop },
+    ];
+    const paths = await resolvePaths({
+      routes,
+      getStaticPaths: async (_route, fullPath) => (fullPath === "/other/:slug" ? ["/other/global"] : []),
+    });
+    expect(paths).toEqual(["/blog/own", "/other/global"]);
+  });
+});
+
+describe("pathToOutputFile", () => {
+  it("maps the root path to index.html", () => {
+    expect(pathToOutputFile("/")).toBe("index.html");
+  });
+
+  it("maps a nested path to <path>/index.html", () => {
+    expect(pathToOutputFile("/about")).toBe("about/index.html");
+    expect(pathToOutputFile("/blog/hello-world")).toBe("blog/hello-world/index.html");
+  });
+
+  it("normalizes surrounding slashes", () => {
+    expect(pathToOutputFile("/about/")).toBe("about/index.html");
+  });
+});

package/src/index.ts

@@ -0,0 +1,233 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import * as nodeModule from "node:module";
+import { dirname, join } from "node:path";
+
+import { createServer, type Plugin, type ResolvedConfig } from "vite";
+
+import type { RouterOptions } from "@praxisjs/router";
+import type { ComponentConstructor } from "@praxisjs/shared/internal";
+
+import type * as PrerenderModule from "./prerender";
+import type { GetStaticPaths, RouteEntry } from "./routes";
+import type { ResolveFnOutput, ResolveHookContext } from "node:module";
+
+export type { GetStaticPaths, RouteEntry, RouteStaticPaths } from "./routes";
+
+export interface SSGConfig {
+  /**
+   * Module specifier exporting the root component as its default export and
+   * the route table (same one passed to `@Router([...])`) as a named
+   * `routes` export, e.g. `"./src/app.tsx"`. Loaded through Vite's own SSR
+   * module graph — not imported directly by `vite.config.ts` — so the config
+   * file itself never needs to resolve JSX/component source.
+   *
+   * A dynamic route can expand itself into concrete paths by declaring its
+   * own `getStaticPaths` directly on the route object (see `RouteEntry`) —
+   * the recommended default, since it's colocated with the route and needs
+   * no path matching. `root` may *also* export a named `getStaticPaths` as a
+   * fallback for routes that don't declare their own; a route's own always
+   * takes precedence.
+   *
+   * Either way, this can only be reached through `root`, never passed as a
+   * plain config value here: Vite's own config loader bundles
+   * `vite.config.ts` with a minimal bundler that inlines relative imports
+   * (only bare package specifiers get externalized) but never lowers TC39
+   * decorators. A `getStaticPaths` written inline in `vite.config.ts` that
+   * reaches a decorated class through a relative import — e.g. one that
+   * loads a `@Collection`-decorated schema to enumerate content slugs —
+   * would bundle that raw decorator syntax straight into the config bundle,
+   * which Node cannot then execute. Exporting it from the same module as
+   * `root` (or from a route reachable from it) avoids this: it only ever
+   * loads through `ssrLoadModule`, which runs the app's real Vite pipeline
+   * (decorator lowering included).
+   */
+  root: string;
+  routerOptions?: RouterOptions;
+  /** CSS selector for the mount container inside `index.html`. Default: `#app`. */
+  containerSelector?: string;
+  /**
+   * Enables client-side hydration (reconciling the prerendered DOM instead of
+   * discarding it). Default: `true`. Set to `false` to fall back to a plain
+   * client remount over the static HTML — no reconciliation runs at all,
+   * client or server, and `render()` in `@praxisjs/runtime` never sees the
+   * hydration marker.
+   */
+  hydrate?: boolean;
+}
+
+// ── extensionless-relative-import retry hook ────────────────────────────────
+//
+// Every other @praxisjs/* package is built with tsc, which emits relative
+// specifiers exactly as written in source ("./router", not "./router.js") —
+// harmless for every consumer so far, since they're all resolved through a
+// bundler (Vite/esbuild/rollup), which resolves extensionless specifiers
+// fine. Node's own ESM resolver does not: it's spec-strict and requires an
+// explicit extension on relative specifiers, and @praxisjs/ssg is the first
+// package here that needs to load that dependency chain (router, core, head,
+// runtime) directly through Node, when `closeBundle` below dynamically
+// imports ./prerender.
+//
+// This lives inline in the package's main entry, with zero relative imports
+// of its own, rather than in a separate module: `registerLoaderHook()` must
+// run *before* anything reachable from this file needs the workaround it
+// installs, and a relative import here would hit the exact problem it's
+// meant to fix before it ever gets the chance to run.
+const RETRYABLE_CODES = new Set(["ERR_MODULE_NOT_FOUND", "ERR_UNSUPPORTED_DIR_IMPORT"]);
+
+function resolveSync(
+  specifier: string,
+  context: ResolveHookContext,
+  nextResolve: (specifier: string, context?: Partial<ResolveHookContext>) => ResolveFnOutput,
+): ResolveFnOutput {
+  try {
+    return nextResolve(specifier, context);
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if ((specifier.startsWith("./") || specifier.startsWith("../")) && code !== undefined && RETRYABLE_CODES.has(code)) {
+      for (const candidate of [`${specifier}.js`, `${specifier}/index.js`]) {
+        try {
+          return nextResolve(candidate, context);
+        } catch {
+          // try the next candidate
+        }
+      }
+    }
+    throw err;
+  }
+}
+
+let hookRegistered = false;
+
+/**
+ * Installs the retry hook above for the rest of this process. Idempotent.
+ * `ssgPlugin()` calls this itself before dynamically importing
+ * `@praxisjs/ssg/prerender` — only needed directly if you're calling
+ * `prerender()` from your own Node script instead of going through
+ * `ssgPlugin()`, and must run before that import.
+ *
+ * Prefers `module.registerHooks()` (in-thread, sync, Node 22.15+) and falls
+ * back to the older `module.register()` (off-thread, needs its own module
+ * file — see loader-hook.ts, the asynchronous twin of `resolveSync` above)
+ * on earlier Node versions.
+ */
+export function registerLoaderHook(): void {
+  if (hookRegistered) return;
+  hookRegistered = true;
+  if (typeof nodeModule.registerHooks === "function") {
+    nodeModule.registerHooks({ resolve: resolveSync });
+  } else {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- intentional fallback for Node < 22.15, which has no registerHooks
+    nodeModule.register(new URL("./loader-hook.js", import.meta.url));
+  }
+}
+
+// ── plugin ───────────────────────────────────────────────────────────────
+
+interface RootModule {
+  default?: ComponentConstructor;
+  routes?: RouteEntry[];
+  getStaticPaths?: GetStaticPaths;
+}
+
+async function loadEntry(
+  resolvedConfig: ResolvedConfig,
+  root: string,
+  withDomGlobals: typeof PrerenderModule.withDomGlobals,
+): Promise<{
+  root: ComponentConstructor;
+  routes: RouteEntry[];
+  getStaticPaths: GetStaticPaths | undefined;
+  close: () => Promise<void>;
+}> {
+  const server = await createServer({
+    configFile: resolvedConfig.configFile,
+    root: resolvedConfig.root,
+    server: { middlewareMode: true, watch: null },
+    appType: "custom",
+    // Every @praxisjs/* package (and anything else in node_modules) must
+    // resolve through plain Node `import()` here — the same path `prerender()`
+    // itself uses to load @praxisjs/core/runtime/router/head — instead of
+    // being re-processed through Vite's SSR transform. Two different copies
+    // of @praxisjs/core would mean two separate component-instance registries:
+    // mountComponent() (from the plain-Node copy prerender.ts imports) would
+    // construct instances that @Router([...])'s decorator (baked into the
+    // Vite-SSR-transformed copy the root module was loaded with) doesn't
+    // recognize as valid components.
+    ssr: { external: true },
+    // No client ever connects to this server and nothing here benefits from
+    // pre-bundling npm deps for browser delivery — and a background
+    // (re-)optimization pass restarting mid-request looked like a plausible
+    // cause of "transport was disconnected" errors on lazy-loaded routes.
+    optimizeDeps: { noDiscovery: true, include: [] },
+  });
+  try {
+    // @Router([...])'s class decorator calls createRouter() at
+    // module-evaluation time — ssrLoadModule() below runs that as a side
+    // effect of importing the root module, so it needs *a* window in place
+    // already, even though nothing is actually being rendered yet (the real,
+    // per-route window gets installed later, in prerender()).
+    const mod = await withDomGlobals("<!doctype html><html><head></head><body></body></html>", "http://localhost/", async () => {
+      return (await server.ssrLoadModule(root)) as RootModule;
+    });
+    if (!mod.default) {
+      throw new Error(`[@praxisjs/ssg] "${root}" has no default export — expected the root component.`);
+    }
+    if (!mod.routes) {
+      throw new Error(`[@praxisjs/ssg] "${root}" has no named "routes" export — expected the same route table passed to @Router([...]).`);
+    }
+    // Left open, closed by the caller after prerender() finishes: routes
+    // wrapped in Lazy(() => import(...)) keep their loader closures bound to
+    // *this* server's module runner for as long as they might still be
+    // invoked — closing it here would break lazy routes on every page after
+    // the first that needs them.
+    return { root: mod.default, routes: mod.routes, getStaticPaths: mod.getStaticPaths, close: () => server.close() };
+  } catch (err) {
+    await server.close();
+    throw err;
+  }
+}
+
+export function ssgPlugin(config: SSGConfig): Plugin {
+  let resolvedConfig: ResolvedConfig;
+
+  // Before anything below ever dynamically imports ./prerender — see the
+  // retry-hook section above for why this needs to happen here.
+  registerLoaderHook();
+
+  return {
+    name: "praxisjs:ssg",
+    apply: "build",
+    configResolved(c) {
+      resolvedConfig = c;
+    },
+    async closeBundle() {
+      const { prerender, withDomGlobals } = (await import("./prerender"));
+
+      const outDir = resolvedConfig.build.outDir;
+      const templatePath = join(resolvedConfig.root, outDir, "index.html");
+      const template = await readFile(templatePath, "utf-8");
+      const { root, routes, getStaticPaths, close } = await loadEntry(resolvedConfig, config.root, withDomGlobals);
+
+      let pages;
+      try {
+        pages = await prerender({
+          root,
+          routes,
+          routerOptions: config.routerOptions,
+          getStaticPaths,
+          template,
+          containerSelector: config.containerSelector,
+          hydrate: config.hydrate,
+        });
+      } finally {
+        await close();
+      }
+
+      for (const page of pages) {
+        const outFile = join(resolvedConfig.root, outDir, page.file);
+        await mkdir(dirname(outFile), { recursive: true });
+        await writeFile(outFile, page.html, "utf-8");
+      }
+    },
+  };
+}

package/src/loader-hook.ts

@@ -0,0 +1,43 @@
+import type { ResolveFnOutput, ResolveHookContext } from "node:module";
+
+// Loaded as a standalone hook module via module.register() (see register.ts)
+// — only used as a fallback on Node versions without the newer, in-thread
+// module.registerHooks() API, so it must have zero relative imports of its
+// own: this file needs to work *before* the extensionless-import problem it
+// exists to fix has been worked around. See register.ts for the full story.
+//
+// Every other @praxisjs/* package is built with tsc, which emits relative
+// specifiers exactly as written in source ("./router", not "./router.js") —
+// harmless for every consumer so far, since they're all resolved through a
+// bundler (Vite/esbuild/rollup), which resolves extensionless specifiers
+// fine. Node's own ESM resolver does not: it's spec-strict and requires an
+// explicit extension on relative specifiers. This hook retries with ".js" /
+// "/index.js" on the two failure modes that produces.
+const RETRYABLE_CODES = new Set(["ERR_MODULE_NOT_FOUND", "ERR_UNSUPPORTED_DIR_IMPORT"]);
+
+type NextResolve = (
+  specifier: string,
+  context?: Partial<ResolveHookContext>,
+) => ResolveFnOutput | Promise<ResolveFnOutput>;
+
+export async function resolve(
+  specifier: string,
+  context: ResolveHookContext,
+  nextResolve: NextResolve,
+): Promise<ResolveFnOutput> {
+  try {
+    return await nextResolve(specifier, context);
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if ((specifier.startsWith("./") || specifier.startsWith("../")) && code !== undefined && RETRYABLE_CODES.has(code)) {
+      for (const candidate of [`${specifier}.js`, `${specifier}/index.js`]) {
+        try {
+          return await nextResolve(candidate, context);
+        } catch {
+          // try the next candidate
+        }
+      }
+    }
+    throw err;
+  }
+}