@solidjs/prerender 0.1.0 → 0.2.0

package/README.md

@@ -45,6 +45,32 @@ export const getPost = query(
 
 Design pages so the crawl exercises the calls the site needs — which happens naturally when pages link to what they use.
 
+## `announceRoutes(router)`
+
+The crawl follows links; a page nothing links to needs announcing. Call this in the app root during render with the `createRouter` instance (or a route-definition tree, with `{ base }`):
+
+```tsx
+import { announceRoutes } from "@solidjs/prerender";
+import { Router } from "./router";
+
+export default function App() {
+  announceRoutes(Router);
+  return <Router>{props => props.children}</Router>;
+}
+```
+
+On the server, when the request is the crawler's, the router's static pages go on the response's hint header and the crawl seeds every one of them. A visitor's response is untouched; in the browser it is a no-op. Dynamic routes (`/posts/:id`) are not announced — only a render knows their values; the crawl finds them by their links. Options: `header` (a custom crawl `hintHeader`), `base`.
+
+It takes either router Solid apps use. With TanStack Router the instance is built per request, so the call goes where the router is — the `start.setup` hook:
+
+```ts
+// src/setup.tsx
+const router = createAppRouter(queryClient, history);
+announceRoutes(router);
+```
+
+The enumerators behind it are exported too — `solidRouterPages(router | routes, { base? })` and `tanstackRouterPages(router)` — for code that wants the path list itself (a sitemap of its own, a hand-rolled `announcePages` call from `prerender-crawler/announce`). Both are pure: they read the router instance's public shape and import nothing from either router package.
+
 ## `serverFunctions(options?)`
 
 The integration has two jobs.
@@ -75,8 +101,9 @@ The client learns the posture from `import.meta.env.PRERENDER_MODE`, which the c
 
 ## Other exports
 
+- `solidRouterPages(router | routes, { base? })`, `tanstackRouterPages(router)` — the static-page enumerators behind `announceRoutes`, pure and isomorphic.
 - `staticCallKey(id, args)` / `staticArtifactPath(id, args)` — the artifact key derivation, for tooling that needs to locate an artifact.
-- Types: `PrerenderedFunction`, `ServerFunctionsIntegration`, `ServerFunctionsIntegrationOptions`, `CaptureSink` (server).
+- Types: `PrerenderedFunction`, `AnnounceableRouter`, `AnnounceRoutesOptions`, `SolidRouterLike`, `SolidRouteLike`, `TanStackRouterLike`, `ServerFunctionsIntegration`, `ServerFunctionsIntegrationOptions`, `CaptureSink` (server).
 
 ## License
 

package/dist/chunk-E6I43WY5.js

@@ -0,0 +1,57 @@
+// src/routers.ts
+function tanstackRouterPages(router) {
+  const paths = /* @__PURE__ */ new Set();
+  for (const [path, route] of Object.entries(router.routesByPath)) {
+    if (path.split("/").some((segment) => segment.includes("$"))) continue;
+    const isIndex = route.fullPath.endsWith("/");
+    const isLeaf = !hasChildren(route.children);
+    if (!isIndex && !isLeaf) continue;
+    paths.add(normalize(path));
+  }
+  return [...paths];
+}
+function solidRouterPages(router, options = {}) {
+  const instance = isSolidRouter(router) ? router : void 0;
+  const routes = instance ? instance.routes : router;
+  const base = options.base ?? instance?.config?.base ?? "";
+  const paths = /* @__PURE__ */ new Set();
+  const walk = (route, prefix) => {
+    const own = route.path === void 0 ? [""] : [].concat(route.path);
+    for (const pattern of own) {
+      const full = join(prefix, pattern);
+      const children = route.children;
+      if (children === void 0) {
+        if (!isDynamic(full)) paths.add(normalize(full));
+        continue;
+      }
+      if (typeof children === "function") continue;
+      for (const child of [].concat(children)) walk(child, full);
+    }
+  };
+  for (const route of [].concat(routes)) walk(route, base);
+  return [...paths];
+}
+function isSolidRouter(value) {
+  if (value === null || Array.isArray(value)) return false;
+  return (typeof value === "function" || typeof value === "object") && "routes" in value;
+}
+var isDynamic = (path) => path.split("/").some((segment) => segment.startsWith(":") || segment.startsWith("*"));
+function hasChildren(children) {
+  if (children === void 0 || children === null) return false;
+  if (Array.isArray(children)) return children.length > 0;
+  return typeof children === "object" ? Object.keys(children).length > 0 : true;
+}
+function join(prefix, path) {
+  const left = prefix.replace(/\/+$/, "");
+  const right = path.replace(/^\/+/, "");
+  return right ? `${left}/${right}` : left || "/";
+}
+function normalize(path) {
+  const trimmed = path.replace(/\/+$/, "");
+  return trimmed === "" ? "/" : trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+export {
+  tanstackRouterPages,
+  solidRouterPages
+};

package/dist/client.d.ts

@@ -1,6 +1,10 @@
-import { P as PrerenderedFunction } from './shared-BcBpMOMU.js';
-export { s as staticArtifactPath, a as staticCallKey } from './shared-BcBpMOMU.js';
+import { A as AnnounceRoutesOptions, P as PrerenderedFunction } from './routers-hMGLsbjF.js';
+export { S as SolidRouteLike, a as SolidRouterLike, b as SolidRouterPagesOptions, T as TanStackRouteLike, c as TanStackRouterLike, s as solidRouterPages, d as staticArtifactPath, e as staticCallKey, t as tanstackRouterPages } from './routers-hMGLsbjF.js';
 
+/** A router `announceRoutes` can read — see the server half. */
+type AnnounceableRouter = unknown;
+/** The client half of `announceRoutes`: there is no request here. Always false. */
+declare function announceRoutes(_router: AnnounceableRouter, _options?: AnnounceRoutesOptions): boolean;
 /**
  * Declares a server function PRERENDERED: it runs at build time, during
  * prerendering, and each call's result is captured as a static JSON
@@ -34,4 +38,4 @@ export { s as staticArtifactPath, a as staticCallKey } from './shared-BcBpMOMU.j
  */
 declare function prerendered<A extends readonly unknown[], R>(fn: (...args: A) => R): PrerenderedFunction<A, Awaited<R>>;
 
-export { PrerenderedFunction, prerendered };
+export { AnnounceRoutesOptions, type AnnounceableRouter, PrerenderedFunction, announceRoutes, prerendered };

package/dist/client.js

@@ -1,3 +1,7 @@
+import {
+  solidRouterPages,
+  tanstackRouterPages
+} from "./chunk-E6I43WY5.js";
 import {
   PRERENDERED_META_KEY,
   staticArtifactPath,
@@ -14,6 +18,9 @@ import {
   isServerFunction,
   withMeta
 } from "@solidjs/web/server-functions/client";
+function announceRoutes(_router, _options) {
+  return false;
+}
 var SERVER_FUNCTION_METADATA = /* @__PURE__ */ Symbol.for("solid.ServerFunctionMetadata");
 function posture() {
   const env = import.meta.env;
@@ -60,7 +67,10 @@ function prerendered(fn) {
   return wrapped;
 }
 export {
+  announceRoutes,
   prerendered,
+  solidRouterPages,
   staticArtifactPath,
-  staticCallKey
+  staticCallKey,
+  tanstackRouterPages
 };

package/dist/routers-hMGLsbjF.d.ts

@@ -0,0 +1,94 @@
+/** What the server wrapper hands the sink per executed static call. */
+interface CaptureSink {
+    capture(id: string, args: readonly unknown[], value: unknown): void | Promise<void>;
+}
+/**
+ * The artifact key of a static call: 128 bits of SHA-256 over the call's
+ * canonical spelling, hex-encoded. Async because hashing is
+ * (`crypto.subtle` is the one SHA-256 both realms share).
+ */
+declare function staticCallKey(id: string, args: readonly unknown[]): Promise<string>;
+/**
+ * The artifact's path relative to the static output root:
+ * `_static/<label>.<key>.json`. The label is a sanitized slice of the
+ * function id — for humans reading a build output or a network tab; the
+ * key alone carries the identity.
+ */
+declare function staticArtifactPath(id: string, args: readonly unknown[]): Promise<string>;
+/**
+ * The public shape of a prerendered reference — mirrors the runtime's
+ * `ServerFunction`: an async callable plus its build-stable identity.
+ */
+interface PrerenderedFunction<A extends readonly unknown[] = unknown[], T = unknown> {
+    (...args: A): Promise<T>;
+    /** The build-stable function id. */
+    readonly id: string;
+    /** The live HTTP address the artifact stands in for (dev fallback, form actions). */
+    readonly url: string;
+}
+/** Options for `announceRoutes`. */
+interface AnnounceRoutesOptions {
+    /** The crawl's `hintHeader`, if configured away from the default. @default "x-prerender" */
+    header?: string;
+    /** The app's base path, when passing a route tree rather than the router instance. */
+    base?: string;
+}
+
+/** The subset of a TanStack `Router` instance this reads. */
+interface TanStackRouterLike {
+    /**
+     * Every route with a path, keyed by full path with the trailing slash
+     * trimmed; where a layout and its index share a path the index wins.
+     * Public on the router instance, built by `@tanstack/router-core`.
+     */
+    routesByPath: Record<string, TanStackRouteLike>;
+}
+interface TanStackRouteLike {
+    /** The route's full path — an index route's ends with `/`. */
+    fullPath: string;
+    children?: unknown;
+}
+/**
+ * The static pages of a TanStack Router instance. A route is a page when
+ * its path has no `$` segment (params `$id`, splats `$`, optional params
+ * `{-$id}`) and it is a leaf or an index — a layout route with children
+ * but no index has no page of its own (its URL renders not-found).
+ *
+ * The router must be a built instance (`createRouter({ routeTree })`): the
+ * generated `routeTree` alone has no full paths until the router
+ * initializes it.
+ */
+declare function tanstackRouterPages(router: TanStackRouterLike): string[];
+/** The subset of a Solid Router `RouteDefinition` this reads. */
+interface SolidRouteLike {
+    /** A pattern, or several — aliases for one route. Absent on a pathless layout. */
+    path?: string | readonly string[];
+    /**
+     * Nested routes, or a thunk producing them lazily. Lazy children are not
+     * enumerated — that would load modules during a render; the crawl finds
+     * those pages by their links.
+     */
+    children?: SolidRouteLike | readonly SolidRouteLike[] | ((...args: never[]) => unknown);
+}
+/** The subset of a Solid Router `createRouter` instance this reads. */
+interface SolidRouterLike {
+    readonly routes: SolidRouteLike | readonly SolidRouteLike[];
+    readonly config?: {
+        base?: string;
+    };
+}
+interface SolidRouterPagesOptions {
+    /** The app's base path, when the tree is passed without its router. */
+    base?: string;
+}
+/**
+ * The static pages of a Solid Router instance (or a route-definition tree).
+ * Paths join root to leaf; a route is a page when it is a leaf — a parent
+ * with children has a page only through an index child (`""` or `"/"`) —
+ * and its joined path has no `:param`, optional `:param?`, or `*splat`
+ * segment. Pathless layouts join through; each alias in a `path` array is
+ * its own page.
+ */
+declare function solidRouterPages(router: SolidRouterLike | SolidRouteLike | readonly SolidRouteLike[], options?: SolidRouterPagesOptions): string[];
+
+export { type AnnounceRoutesOptions as A, type CaptureSink as C, type PrerenderedFunction as P, type SolidRouteLike as S, type TanStackRouteLike as T, type SolidRouterLike as a, type SolidRouterPagesOptions as b, type TanStackRouterLike as c, staticArtifactPath as d, staticCallKey as e, solidRouterPages as s, tanstackRouterPages as t };

package/dist/server.d.ts

@@ -1,6 +1,34 @@
-import { P as PrerenderedFunction } from './shared-BcBpMOMU.js';
-export { C as CaptureSink, s as staticArtifactPath, a as staticCallKey } from './shared-BcBpMOMU.js';
+import { a as SolidRouterLike, S as SolidRouteLike, c as TanStackRouterLike, A as AnnounceRoutesOptions, P as PrerenderedFunction } from './routers-hMGLsbjF.js';
+export { C as CaptureSink, b as SolidRouterPagesOptions, T as TanStackRouteLike, s as solidRouterPages, d as staticArtifactPath, e as staticCallKey, t as tanstackRouterPages } from './routers-hMGLsbjF.js';
 
+/** A router `announceRoutes` can read: Solid Router (instance or tree) or a TanStack Router instance. */
+type AnnounceableRouter = SolidRouterLike | SolidRouteLike | readonly SolidRouteLike[] | TanStackRouterLike;
+/**
+ * Tells a prerender crawl which pages this app's router has — the server
+ * half. Called during a server render or request setup, it reads the
+ * ambient request: when the request is the crawler's, the router's static
+ * pages go on the response's hint header and the crawl seeds every one of
+ * them, linked or not. A visitor's request is untouched; on the client
+ * this is a no-op. Returns whether it announced.
+ *
+ * Takes either router Solid apps use — a Solid Router `createRouter`
+ * instance (or its route-definition tree, with `base`) or a TanStack
+ * Router instance — and tells them apart by shape.
+ *
+ * ```tsx
+ * import { announceRoutes } from "@solidjs/prerender";
+ * import { Router } from "./router";
+ *
+ * export default function App() {
+ *   announceRoutes(Router);
+ *   return <Router>{props => props.children}</Router>;
+ * }
+ * ```
+ *
+ * Dynamic routes (`/posts/:id`, `/posts/$id`) are not announced — only a
+ * render knows their values; the crawl finds them by their links.
+ */
+declare function announceRoutes(router: AnnounceableRouter, options?: AnnounceRoutesOptions): boolean;
 /**
  * Declares a server function PRERENDERED — the server half. Calling the
  * reference during SSR runs the function in-process exactly like a direct
@@ -16,4 +44,4 @@ export { C as CaptureSink, s as staticArtifactPath, a as staticCallKey } from '.
  */
 declare function prerendered<A extends readonly unknown[], R>(fn: (...args: A) => R): PrerenderedFunction<A, Awaited<R>>;
 
-export { PrerenderedFunction, prerendered };
+export { AnnounceRoutesOptions, type AnnounceableRouter, PrerenderedFunction, SolidRouteLike, SolidRouterLike, TanStackRouterLike, announceRoutes, prerendered };

package/dist/server.js

@@ -1,3 +1,7 @@
+import {
+  solidRouterPages,
+  tanstackRouterPages
+} from "./chunk-E6I43WY5.js";
 import {
   CAPTURE_SINK,
   PRERENDERED_META_KEY,
@@ -12,6 +16,16 @@ import {
   getServerFunctionMetadata,
   isServerFunction
 } from "@solidjs/web/server-functions/server";
+import { getRequestEvent } from "@solidjs/web";
+import { announcePages } from "prerender-crawler/announce";
+function announceRoutes(router, options = {}) {
+  const event = getRequestEvent();
+  if (!event?.response || event.response.committed) return false;
+  if (!event.request.headers.has(options.header ?? "x-prerender")) return false;
+  const pages = isTanStackRouter(router) ? tanstackRouterPages(router) : solidRouterPages(router, { base: options.base });
+  return announcePages(event.request, event.response.headers, pages, { header: options.header });
+}
+var isTanStackRouter = (router) => typeof router === "object" && router !== null && "routesByPath" in router;
 var SERVER_FUNCTION_METADATA = /* @__PURE__ */ Symbol.for("solid.ServerFunctionMetadata");
 function prerendered(fn) {
   if (!isServerFunction(fn)) {
@@ -36,7 +50,10 @@ function prerendered(fn) {
   return wrapped;
 }
 export {
+  announceRoutes,
   prerendered,
+  solidRouterPages,
   staticArtifactPath,
-  staticCallKey
+  staticCallKey,
+  tanstackRouterPages
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidjs/prerender",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Solid's integration for prerender-crawler: prerendered() turns server functions into build-time data captured as static artifacts, and the serverFunctions() integration captures them during the crawl and guards static builds against calls nothing prerendered.",
   "license": "MIT",
   "author": "Ryan Carniato",
@@ -49,13 +49,15 @@
     "prerender-crawler": ">=0.1.0"
   },
   "devDependencies": {
+    "@solidjs/router": "^2.0.0-next.21",
     "@solidjs/web": "^2.0.0-rc.6",
+    "@tanstack/router-core": "^1.168.0",
     "@types/node": "^22.0.0",
     "solid-js": "^2.0.0-rc.6",
     "tsup": "^8.5.0",
     "typescript": "^5.8.0",
     "vitest": "^4.0.0",
-    "prerender-crawler": "^0.1.0"
+    "prerender-crawler": "^0.2.0"
   },
   "scripts": {
     "build": "rm -rf dist && tsup",

package/dist/shared-BcBpMOMU.d.ts

@@ -1,30 +0,0 @@
-/** What the server wrapper hands the sink per executed static call. */
-interface CaptureSink {
-    capture(id: string, args: readonly unknown[], value: unknown): void | Promise<void>;
-}
-/**
- * The artifact key of a static call: 128 bits of SHA-256 over the call's
- * canonical spelling, hex-encoded. Async because hashing is
- * (`crypto.subtle` is the one SHA-256 both realms share).
- */
-declare function staticCallKey(id: string, args: readonly unknown[]): Promise<string>;
-/**
- * The artifact's path relative to the static output root:
- * `_static/<label>.<key>.json`. The label is a sanitized slice of the
- * function id — for humans reading a build output or a network tab; the
- * key alone carries the identity.
- */
-declare function staticArtifactPath(id: string, args: readonly unknown[]): Promise<string>;
-/**
- * The public shape of a prerendered reference — mirrors the runtime's
- * `ServerFunction`: an async callable plus its build-stable identity.
- */
-interface PrerenderedFunction<A extends readonly unknown[] = unknown[], T = unknown> {
-    (...args: A): Promise<T>;
-    /** The build-stable function id. */
-    readonly id: string;
-    /** The live HTTP address the artifact stands in for (dev fallback, form actions). */
-    readonly url: string;
-}
-
-export { type CaptureSink as C, type PrerenderedFunction as P, staticCallKey as a, staticArtifactPath as s };