@solidjs/prerender 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Carniato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @solidjs/prerender
+
+Static server functions for Solid. `prerendered()` declares that a `'use server'` function runs at build time — during prerendering — and that each call's result is captured as a static artifact the deployed client fetches instead of calling a server. Pair it with [`prerender-crawler`](../crawler) and `vite build` produces a folder of files that is a complete Solid app with typed server-side data loading and no server.
+
+Requires `@solidjs/web` 2 (server functions) and `@solidjs/vite-plugin` with `serverFunctions: true`.
+
+## Setup
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import solid from "@solidjs/vite-plugin";
+import { prerender } from "prerender-crawler/vite";
+import { serverFunctions } from "@solidjs/prerender/integration";
+
+export default defineConfig({
+  plugins: [
+    solid({ start: true, ssr: true, serverFunctions: true }),
+    prerender({ mode: "static", integrations: [serverFunctions()] })
+  ]
+});
+```
+
+`prerender` is the generic crawler; `serverFunctions()` is the Solid integration that captures `prerendered()` calls during the crawl and guards the build.
+
+## `prerendered(fn)`
+
+```ts
+import { query } from "@solidjs/router";
+import { prerendered } from "@solidjs/prerender";
+
+export const getPost = query(
+  prerendered(async (slug: string) => {
+    "use server";
+    return db.posts.find(slug); // runs at build time in a prerendered build
+  }),
+  "post"
+);
+```
+
+- **Implies `GET`.** A prerendered call is by definition a safe read. Outside a prerendered build — the dev server, or a build without the prerender plugin — the reference behaves exactly like `GET(fn)`, so the app still works against a live server. Dev stays fullstack; production is static.
+- **Arguments are the address.** Each call identity (function id + arguments) becomes one artifact under `_static/`. Both the build and the client derive the key from the arguments, so they must be JSON-safe and spell identically in both realms.
+- **Results are unrestricted.** JSON-safe results are stored as plain JSON; rich values (Dates, Maps, typed errors) ride the server-function codec into the artifact, so whatever survives a live call survives the artifact.
+- **Only calls the build made have artifacts.** In a static build, a client calling with arguments no prerendered page used gets a rejected call (there is no server). In a hybrid build the call falls back to the live server.
+
+Design pages so the crawl exercises the calls the site needs — which happens naturally when pages link to what they use.
+
+## `serverFunctions(options?)`
+
+The integration has two jobs.
+
+**Capture.** For the crawl's duration every executed `prerendered` call is collected (the crawl is in-process, so the built server bundle and the integration share a realm), encoded once per call identity, and emitted alongside the pages.
+
+**The guard.** `@solidjs/vite-plugin` records every server function the client build can dispatch. After the crawl, any of those ids nothing captured is a call a static deployment cannot answer — because the function lacks `prerendered()`, or because no prerendered page called it. In static mode the build fails naming each one:
+
+```
+[@solidjs/prerender] 1 server function(s) the client can call were never captured during prerendering:
+  - getLiveCount (getLiveCount-1679f63b, src/data.ts)
+A static deployment has no server to answer them, so these calls fail at runtime. ...
+```
+
+| Option       | Default                              |                                                                                                               |
+| ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `uncaptured` | `"error"` static / `"ignore"` hybrid | `"error"`, `"warn"`, or `"ignore"`.                                                                           |
+| `codec`      |                                      | Codec options for encoding rich results; must match the client's `configureServerFunctionsClient({ codec })`. |
+
+The guard needs a `@solidjs/vite-plugin` that records function ids in `.vite/solid-server-functions.json`; with an older version it warns that it cannot verify and lets the build through.
+
+## Modes
+
+- **`prerender({ mode: "static" })`** — SSG. Every page written, every `prerendered()` call baked, missing artifact is an error. Deploy `dist/client` to any static host.
+- **`prerender({ mode: "hybrid" })`** — a live server is deployed too. Chosen calls are baked to static artifacts while everything else stays live; clients fetch artifacts first and fall back to the server. Pages aren't written by default (a static file would shadow live SSR).
+
+The client learns the posture from `import.meta.env.PRERENDER_MODE`, which the crawler's Vite plugin defines. No plugin, no constant, live behavior.
+
+## Other exports
+
+- `staticCallKey(id, args)` / `staticArtifactPath(id, args)` — the artifact key derivation, for tooling that needs to locate an artifact.
+- Types: `PrerenderedFunction`, `ServerFunctionsIntegration`, `ServerFunctionsIntegrationOptions`, `CaptureSink` (server).
+
+## License
+
+MIT

package/dist/chunk-XX54FQA3.js

@@ -0,0 +1,74 @@
+// src/shared.ts
+var ARTIFACT_DIR = "_static";
+var CAPTURE_SINK = /* @__PURE__ */ Symbol.for("solid-prerender.captureArtifacts");
+function canonicalJSON(value) {
+  return writeCanonical(value, /* @__PURE__ */ new Set());
+}
+function writeCanonical(value, ancestors) {
+  if (value === null) return "null";
+  const t = typeof value;
+  if (t === "string") return JSON.stringify(value);
+  if (t === "boolean") return value ? "true" : "false";
+  if (t === "number") {
+    const n = value;
+    if (!Number.isFinite(n) || Object.is(n, -0)) {
+      throw notJSONSafe(`the number ${Object.is(n, -0) ? "-0" : String(n)}`);
+    }
+    return JSON.stringify(n);
+  }
+  if (t !== "object") throw notJSONSafe(`a ${t}`);
+  const obj = value;
+  if (ancestors.has(obj)) throw notJSONSafe("a cyclic structure");
+  ancestors.add(obj);
+  let out;
+  if (Array.isArray(obj)) {
+    let body = "";
+    for (let i = 0; i < obj.length; i++) {
+      if (!(i in obj)) throw notJSONSafe("a sparse array");
+      body += (i ? "," : "") + writeCanonical(obj[i], ancestors);
+    }
+    out = "[" + body + "]";
+  } else {
+    const proto = Object.getPrototypeOf(obj);
+    if (proto !== Object.prototype && proto !== null) {
+      throw notJSONSafe(`an instance of ${proto?.constructor?.name ?? "a null-free prototype"}`);
+    }
+    const keys = Object.keys(obj).sort();
+    let body = "";
+    for (let i = 0; i < keys.length; i++) {
+      const v = obj[keys[i]];
+      if (v === void 0) throw notJSONSafe("an undefined property");
+      body += (i ? "," : "") + JSON.stringify(keys[i]) + ":" + writeCanonical(v, ancestors);
+    }
+    out = "{" + body + "}";
+  }
+  ancestors.delete(obj);
+  return out;
+}
+function notJSONSafe(what) {
+  return new Error(
+    `Static function arguments must be JSON-safe \u2014 they are the call's address, and both the build and the client must derive the same artifact key from them. Got ${what}. Rich values belong in the function's RESULT (which rides the codec), not its arguments.`
+  );
+}
+async function staticCallKey(id, args) {
+  const spelling = canonicalJSON([id, ...args]);
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(spelling));
+  const bytes = new Uint8Array(digest).subarray(0, 16);
+  let hex = "";
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, "0");
+  return hex;
+}
+async function staticArtifactPath(id, args) {
+  const key = await staticCallKey(id, args);
+  const label = id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 48);
+  return `${ARTIFACT_DIR}/${label ? label + "." : ""}${key}.json`;
+}
+var PRERENDERED_META_KEY = "prerendered";
+
+export {
+  CAPTURE_SINK,
+  canonicalJSON,
+  staticCallKey,
+  staticArtifactPath,
+  PRERENDERED_META_KEY
+};

package/dist/client.d.ts

@@ -0,0 +1,37 @@
+import { P as PrerenderedFunction } from './shared-BcBpMOMU.js';
+export { s as staticArtifactPath, a as staticCallKey } from './shared-BcBpMOMU.js';
+
+/**
+ * Declares a server function PRERENDERED: it runs at build time, during
+ * prerendering, and each call's result is captured as a static JSON
+ * artifact addressed by the call's identity (function id + arguments).
+ * Clients of the built site fetch the artifact instead of invoking a
+ * server — a static deploy serves typed, codec-faithful data with no
+ * runtime server at all.
+ *
+ * The declaration implies `GET`: a prerendered call is by definition a
+ * safe read (its result is baked into the build), and outside a
+ * prerendered build — the dev server, or a build without the prerender
+ * plugin — the reference behaves exactly like `GET(fn)`, so the app still
+ * works against a live server.
+ *
+ * Arguments must be JSON-safe: they are the call's ADDRESS (both the
+ * build and the client derive the artifact key from them), so they must
+ * spell identically in both realms. Results are unrestricted — rich values
+ * (Dates, Maps, typed errors) ride the codec into the artifact.
+ *
+ * Only calls that actually happen during prerendering have artifacts. In a
+ * static build, a client calling with arguments no prerendered page used
+ * gets a rejected call (there is no server to fall back to); in a hybrid
+ * build the call falls back to the live server.
+ *
+ * ```ts
+ * export const getPosts = prerendered(async (tag: string) => {
+ *   "use server";
+ *   return db.posts.byTag(tag); // runs at build time in a prerendered build
+ * });
+ * ```
+ */
+declare function prerendered<A extends readonly unknown[], R>(fn: (...args: A) => R): PrerenderedFunction<A, Awaited<R>>;
+
+export { PrerenderedFunction, prerendered };

package/dist/client.js

@@ -0,0 +1,66 @@
+import {
+  PRERENDERED_META_KEY,
+  staticArtifactPath,
+  staticCallKey
+} from "./chunk-XX54FQA3.js";
+
+// src/client.ts
+import {
+  GET,
+  SERVER_FUNCTION_INVOKE,
+  deserializeStream,
+  getServerFunctionMetadata,
+  getServerFunctionsCodec,
+  isServerFunction,
+  withMeta
+} from "@solidjs/web/server-functions/client";
+var SERVER_FUNCTION_METADATA = /* @__PURE__ */ Symbol.for("solid.ServerFunctionMetadata");
+function posture() {
+  const env = import.meta.env;
+  const mode = env?.PRERENDER_MODE;
+  return {
+    mode: mode === "static" || mode === "hybrid" ? mode : void 0,
+    base: typeof env?.BASE_URL === "string" ? env.BASE_URL : "/"
+  };
+}
+function prerendered(fn) {
+  if (!isServerFunction(fn)) {
+    throw new Error("prerendered expects a server function reference");
+  }
+  const source = getServerFunctionMetadata(fn)?.method === "GET" ? fn : GET(fn);
+  if (posture().mode === void 0) {
+    return withMeta(source, { [PRERENDERED_META_KEY]: true });
+  }
+  const id = source.id;
+  const run = async (args, options) => {
+    const { mode, base } = posture();
+    const path = await staticArtifactPath(id, args);
+    const url = base.endsWith("/") ? base + path : `${base}/${path}`;
+    const response = await fetch(url, options?.signal ? { signal: options.signal } : void 0);
+    if (!response.ok) {
+      if (mode === "hybrid") {
+        return source[SERVER_FUNCTION_INVOKE](args, options);
+      }
+      throw new Error(
+        `No static artifact for this call of "${id}" (${response.status} at ${url}): only calls made during prerendering are captured. Prerender a page that performs this call (same arguments), or make the function a live server function.`
+      );
+    }
+    const text = await response.text();
+    if (text === "") return void 0;
+    return text.startsWith(";0x") ? await deserializeStream(new Response(text), getServerFunctionsCodec()) : JSON.parse(text);
+  };
+  const wrapped = ((...args) => run(args));
+  wrapped[SERVER_FUNCTION_METADATA] = {
+    ...getServerFunctionMetadata(source),
+    [PRERENDERED_META_KEY]: true
+  };
+  wrapped[SERVER_FUNCTION_INVOKE] = run;
+  wrapped.id = id;
+  Object.defineProperty(wrapped, "url", { get: () => source.url, configurable: true });
+  return wrapped;
+}
+export {
+  prerendered,
+  staticArtifactPath,
+  staticCallKey
+};

package/dist/integration.d.ts

@@ -0,0 +1,39 @@
+import { PrerenderIntegration } from 'prerender-crawler';
+
+interface ServerFunctionsIntegrationOptions {
+    /**
+     * Codec options for encoding artifacts that carry rich (non-JSON-safe)
+     * results. Must match the CLIENT's configured codec
+     * (`configureServerFunctionsClient({ codec })`) — the artifact is decoded
+     * there. Plain JSON-safe results never touch the codec.
+     */
+    codec?: unknown;
+    /**
+     * What to do when the client build references server functions the crawl
+     * never captured — calls a static deployment cannot answer (no server),
+     * whether the function lacks `prerendered()` or no prerendered page ever
+     * called it. `"error"` fails the build naming each one.
+     * @default "error" in static mode, "ignore" in hybrid (a server exists)
+     */
+    uncaptured?: "error" | "warn" | "ignore";
+}
+/** The integration, with the ids it saw — what the guard checks against. */
+interface ServerFunctionsIntegration extends PrerenderIntegration {
+    /** Every server-function id captured at least once during the crawl. */
+    readonly captured: ReadonlySet<string>;
+}
+/**
+ * The Solid server-functions integration for a prerender run: captures
+ * `prerendered()` results as static artifacts and, in static mode, fails
+ * the build if the client can reach server functions nothing prerendered.
+ *
+ * ```ts
+ * import { prerender } from "prerender-crawler/vite";
+ * import { serverFunctions } from "@solidjs/prerender/integration";
+ *
+ * prerender({ mode: "static", integrations: [serverFunctions()] })
+ * ```
+ */
+declare function serverFunctions(options?: ServerFunctionsIntegrationOptions): ServerFunctionsIntegration;
+
+export { type ServerFunctionsIntegration, type ServerFunctionsIntegrationOptions, serverFunctions };

package/dist/integration.js

@@ -0,0 +1,77 @@
+import {
+  CAPTURE_SINK,
+  canonicalJSON,
+  staticArtifactPath
+} from "./chunk-XX54FQA3.js";
+
+// src/integration.ts
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+var MANIFEST_PATH = ".vite/solid-server-functions.json";
+function serverFunctions(options = {}) {
+  const artifacts = /* @__PURE__ */ new Map();
+  const captured = /* @__PURE__ */ new Set();
+  const globals = globalThis;
+  return {
+    name: "solid:server-functions",
+    captured,
+    setup() {
+      globals[CAPTURE_SINK] = {
+        async capture(id, args, value) {
+          captured.add(id);
+          const filename = await staticArtifactPath(id, args);
+          let payload = artifacts.get(filename);
+          if (!payload) {
+            payload = encodeArtifact(value, options.codec);
+            artifacts.set(filename, payload);
+          }
+          await payload;
+        }
+      };
+    },
+    async teardown(context) {
+      delete globals[CAPTURE_SINK];
+      guard(context, captured, options.uncaptured);
+      for (const [filename, payload] of artifacts) {
+        context.emitFile({ filename, contents: await payload });
+      }
+    }
+  };
+}
+function guard(context, captured, policy = context.mode === "static" ? "error" : "ignore") {
+  if (policy === "ignore") return;
+  const file = path.join(context.outDir, MANIFEST_PATH);
+  if (!existsSync(file)) return;
+  const manifest = JSON.parse(readFileSync(file, "utf8"));
+  if (Array.isArray(manifest) || !manifest.functions) {
+    console.warn(
+      `[@solidjs/prerender] ${MANIFEST_PATH} carries no function ids, so the static-mode guard cannot verify that every client-reachable server function was prerendered. Upgrade @solidjs/vite-plugin to a version that records them.`
+    );
+    return;
+  }
+  const uncaptured = manifest.functions.filter((fn) => !captured.has(fn.id));
+  if (uncaptured.length === 0) return;
+  const lines = uncaptured.map((fn) => `  - ${fn.name} (${fn.id}, ${fn.module})`);
+  const message = `[@solidjs/prerender] ${uncaptured.length} server function(s) the client can call were never captured during prerendering:
+${lines.join("\n")}
+A static deployment has no server to answer them, so these calls fail at runtime. Wrap each in prerendered() and make sure a prerendered page performs the call (same arguments); calls that must stay live \u2014 mutations, per-request data \u2014 need a deployed server (mode: "hybrid"). Set uncaptured: "warn" on serverFunctions() to build anyway.`;
+  if (policy === "error") throw new Error(message);
+  console.warn(message);
+}
+async function encodeArtifact(value, codec) {
+  if (value === void 0) return "";
+  try {
+    return canonicalJSON(value);
+  } catch {
+    const { serializeResponseStream } = await import("@solidjs/web/server-functions/server");
+    return await new Response(
+      serializeResponseStream(
+        value,
+        codec
+      )
+    ).text();
+  }
+}
+export {
+  serverFunctions
+};

package/dist/server.d.ts

@@ -0,0 +1,19 @@
+import { P as PrerenderedFunction } from './shared-BcBpMOMU.js';
+export { C as CaptureSink, s as staticArtifactPath, a as staticCallKey } from './shared-BcBpMOMU.js';
+
+/**
+ * Declares a server function PRERENDERED — the server half. Calling the
+ * reference during SSR runs the function in-process exactly like a direct
+ * server-function call; during prerendering (when the prerender
+ * integration has installed its capture sink) each call's settled result
+ * is additionally captured as a static artifact keyed by the call's
+ * identity. The declaration implies `GET` — it registers the id's GET
+ * grant so the client's live fallback (dev, plugin-less builds) can
+ * dispatch over HTTP GET.
+ *
+ * See the client half (the browser build of this module) for the full
+ * declaration contract.
+ */
+declare function prerendered<A extends readonly unknown[], R>(fn: (...args: A) => R): PrerenderedFunction<A, Awaited<R>>;
+
+export { PrerenderedFunction, prerendered };

package/dist/server.js

@@ -0,0 +1,42 @@
+import {
+  CAPTURE_SINK,
+  PRERENDERED_META_KEY,
+  staticArtifactPath,
+  staticCallKey
+} from "./chunk-XX54FQA3.js";
+
+// src/server.ts
+import {
+  GET,
+  SERVER_FUNCTION_INVOKE,
+  getServerFunctionMetadata,
+  isServerFunction
+} from "@solidjs/web/server-functions/server";
+var SERVER_FUNCTION_METADATA = /* @__PURE__ */ Symbol.for("solid.ServerFunctionMetadata");
+function prerendered(fn) {
+  if (!isServerFunction(fn)) {
+    throw new Error("prerendered expects a server function reference");
+  }
+  const source = getServerFunctionMetadata(fn)?.method === "GET" ? fn : GET(fn);
+  const id = source.id;
+  const run = async (args, options) => {
+    const value = await source[SERVER_FUNCTION_INVOKE](args, options);
+    const sink = globalThis[CAPTURE_SINK];
+    if (sink) await sink.capture(id, args, value);
+    return value;
+  };
+  const wrapped = ((...args) => run(args));
+  wrapped[SERVER_FUNCTION_METADATA] = {
+    ...getServerFunctionMetadata(source),
+    [PRERENDERED_META_KEY]: true
+  };
+  wrapped[SERVER_FUNCTION_INVOKE] = run;
+  wrapped.id = id;
+  Object.defineProperty(wrapped, "url", { get: () => source.url, configurable: true });
+  return wrapped;
+}
+export {
+  prerendered,
+  staticArtifactPath,
+  staticCallKey
+};

package/dist/shared-BcBpMOMU.d.ts

@@ -0,0 +1,30 @@
+/** 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 };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@solidjs/prerender",
+  "version": "0.1.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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/solidjs/prerender-crawler",
+    "directory": "packages/solid"
+  },
+  "homepage": "https://github.com/solidjs/prerender-crawler/tree/main/packages/solid#readme",
+  "bugs": "https://github.com/solidjs/prerender-crawler/issues",
+  "keywords": [
+    "solid",
+    "solidjs",
+    "prerender",
+    "static site generation",
+    "ssg",
+    "server functions"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/client.d.ts",
+        "default": "./dist/client.js"
+      },
+      "default": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      }
+    },
+    "./integration": {
+      "types": "./dist/integration.d.ts",
+      "default": "./dist/integration.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@solidjs/web": ">=2.0.0-rc.6",
+    "prerender-crawler": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@solidjs/web": "^2.0.0-rc.6",
+    "@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"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}