@rivetjs/router 0.1.0-alpha.0 → 0.1.0-alpha.1

package/build/reach.js

@@ -0,0 +1,302 @@
+// Server reach (SERVER-REACH, spec docs/design/specs/2026-10-20-server-reach-design.md): which server-only modules each
+// route's browser graph reaches, before the build. A page route that reaches one through its own module and plain
+// helper modules becomes a document route (links load its document; its module leaves the client build); a component
+// module on the way (shared, client-rendered on every client navigation to the routes using it), a layout or an error
+// page reaching one is RV3011. Build-time only (Node): sources are read, compiled / type-stripped and parsed here.
+import { readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { parseSync, transformWithOxc } from "vite";
+import { compile } from "@rivetjs/compiler";
+import { docsUrl } from "@rivetjs/compiler/codes";
+import { isServerOnly, SERVER_ONLY_MARKER } from "@rivetjs/compiler/vite";
+export const RV_REACH = "RV3011";
+const SCANNED = /\.[cm]?[jt]sx?$/;
+const COMPONENT = /\.[jt]sx$/;
+// Browser imports per module, by mtime (dev re-runs read only changed files).
+const edgeCache = new Map();
+function namesOf(entries) {
+    return entries.map(({ importName }) => (importName.kind === "Name" ? importName.name : importName.kind === "Default" ? "default" : "*"));
+}
+/** Browser imports of one module: route modules after the server split, `.tsx` as the compiler emits them, `.ts` type-stripped. */
+async function edgesOf(file, route, config) {
+    let mtime;
+    try {
+        mtime = statSync(file).mtimeMs;
+    }
+    catch {
+        return [];
+    }
+    const cached = edgeCache.get(file);
+    if (cached && cached.mtime === mtime && cached.route === route)
+        return cached.edges;
+    const source = readFileSync(file, "utf8");
+    let code;
+    if (route || COMPONENT.test(file)) {
+        const result = compile(source, { target: "dom", filename: file, ...(route ? { serverExports: true } : {}) });
+        // A module that does not compile fails the real build with its own diagnostic; scan its imports as written.
+        if (!result.diagnostics.length)
+            code = result.code;
+    }
+    if (code === undefined && /\.[cm]?[jt]sx?$/.test(file) && !/\.[cm]?js$/.test(file))
+        code = (await transformWithOxc(source, file, { jsx: "preserve" }, undefined, config).catch(() => ({ code: source }))).code;
+    const parsed = parseSync(file.replace(/\.[^./\\]+$/, ".jsx"), code ?? source);
+    const edges = [];
+    const text = code ?? source;
+    for (const item of parsed.module.staticImports) {
+        // Type-only entries survive only where stripping failed: never browser imports.
+        const entries = item.entries.filter((entry) => !entry.isType);
+        if (item.entries.length && !entries.length)
+            continue;
+        edges.push({ spec: item.moduleRequest.value, names: namesOf(entries) });
+    }
+    for (const item of parsed.module.staticExports)
+        for (const entry of item.entries)
+            if (entry.moduleRequest && !entry.isType)
+                edges.push({ spec: entry.moduleRequest.value, names: entry.importName.kind === "Name" ? [entry.importName.name] : ["*"] });
+    for (const item of parsed.module.dynamicImports) {
+        const literal = /^\s*(["'`])([^"'`$]*)\1\s*$/.exec(text.slice(item.moduleRequest.start, item.moduleRequest.end));
+        if (literal)
+            edges.push({ spec: literal[2], names: ["*"] });
+    }
+    edgeCache.set(file, { mtime, route, edges });
+    return edges;
+}
+/** Display path: root-relative inside the root, else `<package name>/<path in the package>`. */
+function displayer(root) {
+    const packages = new Map();
+    const packageOf = (dir) => {
+        for (let at = dir;; at = dirname(at)) {
+            let name = packages.get(at);
+            if (name === undefined) {
+                try {
+                    name = JSON.parse(readFileSync(join(at, "package.json"), "utf8")).name ?? null;
+                }
+                catch {
+                    name = null;
+                }
+                packages.set(at, name);
+            }
+            if (name)
+                return { dir: at, name };
+            if (dirname(at) === at)
+                return null;
+        }
+    };
+    return (id) => {
+        if (!isAbsolute(id))
+            return id;
+        const rel = relative(root, id);
+        if (!rel.startsWith("..") && !isAbsolute(rel))
+            return rel.split(sep).join("/");
+        const pkg = packageOf(dirname(id));
+        return pkg ? pkg.name + "/" + relative(pkg.dir, id).split(sep).join("/") : id;
+    };
+}
+const list = (routes) => (routes.length <= 5 ? routes.join(", ") : routes.slice(0, 5).join(", ") + ` and ${routes.length - 5} more`);
+/** Walk every route's browser graph and classify the routes (see the module comment). */
+export async function analyzeReach(options) {
+    const { root, routesDir, table, serverOnly, routeModules } = options;
+    const show = displayer(root);
+    const abs = (file) => join(routesDir, file);
+    const graph = new Map();
+    const resolved = new Map();
+    const resolveCached = async (spec, importer) => {
+        const key = importer + "\0" + spec;
+        if (!resolved.has(key))
+            resolved.set(key, await options.resolve(spec, importer).catch(() => undefined));
+        return resolved.get(key);
+    };
+    const scannable = (id) => isAbsolute(id) && !id.includes("?") && !id.includes("\0") && SCANNED.test(id) && !id.split(sep).includes("node_modules");
+    const visit = async (seeds) => {
+        const queue = seeds.filter((seed) => !graph.has(seed));
+        for (const seed of queue)
+            graph.set(seed, []);
+        while (queue.length) {
+            const file = queue.shift();
+            const targets = [];
+            for (const edge of await edgesOf(file, routeModules.has(file), options.config)) {
+                const id = await resolveCached(edge.spec, file);
+                const clean = id?.split("?")[0];
+                if (isServerOnly(serverOnly, edge.spec, clean)) {
+                    targets.push({ key: id === undefined || id.startsWith("\0") ? edge.spec : clean, serverOnly: true, spec: edge.spec, names: edge.names });
+                    continue;
+                }
+                if (!id || !scannable(id))
+                    continue;
+                targets.push({ key: id, serverOnly: false, spec: edge.spec, names: edge.names });
+                if (!graph.has(id))
+                    (graph.set(id, []), queue.push(id));
+            }
+            graph.set(file, targets);
+        }
+    };
+    const pages = [...new Set(table.routes.flatMap((route) => (route.page ? [route.page] : [])))];
+    const layouts = [...new Set(table.routes.flatMap((route) => route.layouts.flatMap((layout) => (layout.page ? [layout.page] : []))))];
+    const specials = [
+        ...new Set([
+            table.notFound,
+            table.error,
+            ...(table.notFounds ?? []).map((entry) => entry.page),
+            ...table.routes.flatMap((route) => [route.notFound, route.error]),
+        ].filter((file) => !!file)),
+    ];
+    await visit([...pages, ...layouts, ...specials].map(abs));
+    // Fixpoints (monotone booleans over a graph with cycles): reaches a server-only module; reaches one through a component.
+    const reaches = new Set(), viaComponent = new Set();
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const [file, targets] of graph) {
+            if (!reaches.has(file) && targets.some((t) => t.serverOnly || reaches.has(t.key)))
+                (reaches.add(file), (changed = true));
+            if (!viaComponent.has(file) && targets.some((t) => !t.serverOnly && ((COMPONENT.test(t.key) && reaches.has(t.key)) || viaComponent.has(t.key))))
+                (viaComponent.add(file), (changed = true));
+        }
+    }
+    // Shortest display chain from `from` to a server-only module; `component`: through a component module (not `from`).
+    const chainFrom = (from, component) => {
+        const seen = new Set([from + "\0" + !component]);
+        const queue = [{ file: from, passed: !component, back: null }];
+        while (queue.length) {
+            const state = queue.shift();
+            for (const target of graph.get(state.file) ?? []) {
+                if (target.serverOnly) {
+                    if (!state.passed)
+                        continue;
+                    const files = [];
+                    for (let at = state; at; at = at.back)
+                        files.unshift(at.file);
+                    // Component chains start at the first component (the page and its helpers are the routes' own).
+                    const first = component ? files.findIndex((file, i) => i > 0 && COMPONENT.test(file)) : 0;
+                    return [...files.slice(Math.max(first, 0)).map(show), target.key.startsWith("/") ? show(target.key) : target.key];
+                }
+                const passed = state.passed || COMPONENT.test(target.key);
+                const key = target.key + "\0" + passed;
+                if (seen.has(key) || !reaches.has(target.key))
+                    continue;
+                seen.add(key);
+                queue.push({ file: target.key, passed, back: state });
+            }
+        }
+        return [show(from)];
+    };
+    const reachMode = options.reach ?? "error";
+    const documents = new Map();
+    const problems = [];
+    const byChain = new Map();
+    const patternsOf = (page) => table.routes.filter((route) => route.page === page).map((route) => route.pattern);
+    for (const page of pages) {
+        const file = abs(page);
+        if (!reaches.has(file))
+            continue;
+        const targets = graph.get(file) ?? [];
+        // `import "@rivetjs/router/server-only"` in the page module: the page itself is server-rendered only.
+        const declared = targets.some((t) => t.serverOnly && t.spec === SERVER_ONLY_MARKER);
+        const component = !declared && targets.some((t) => !t.serverOnly && ((COMPONENT.test(t.key) && reaches.has(t.key)) || viaComponent.has(t.key)));
+        if (component) {
+            const chain = chainFrom(file, true);
+            const key = chain.join("\0");
+            let group = byChain.get(key);
+            if (!group)
+                byChain.set(key, (group = { chain, routes: new Set(), files: new Set() }));
+            for (const pattern of patternsOf(page))
+                group.routes.add(pattern);
+            group.files.add(page);
+            if (reachMode === "error")
+                continue;
+        }
+        documents.set(page, chainFrom(file, false));
+    }
+    const docs = "\n  docs: " + docsUrl(RV_REACH);
+    for (const { chain, routes, files } of byChain.values()) {
+        const severity = reachMode === "warn" ? "warning" : "error";
+        const what = routes.size === 1 ? "client-navigated page route" : "client-navigated page routes";
+        problems.push({
+            severity,
+            kind: "component",
+            chain,
+            routes: [...routes],
+            files: [...files],
+            message: `[rivet:router] ${RV_REACH} ${chain.join(" → ")} (server-only), rendered by ${list([...routes])} (${what})` +
+                (severity === "warning" ? "; rendered as document routes (links load their documents)" : "") +
+                "\n  fix: pass the data to the component as props (inlined at build time, or read in the page's `load(…)`), keep server-only modules out of components, or make the page a document route (`import \"" +
+                SERVER_ONLY_MARKER +
+                '"` in the page module); `rivetRouter({ serverOnly: { reach: "warn" } })` turns this into a warning (those pages render as document routes)' +
+                docs,
+        });
+    }
+    for (const [kind, files] of [
+        ["layout", layouts],
+        ["special", specials],
+    ])
+        for (const page of files) {
+            const file = abs(page);
+            if (!reaches.has(file))
+                continue;
+            const chain = chainFrom(file, false);
+            const folder = dirname(page) === "." ? "" : "/" + dirname(page).split(sep).join("/");
+            const routes = kind === "layout"
+                ? table.routes.filter((route) => route.page && route.layouts.some((layout) => layout.page === page)).map((route) => route.pattern)
+                : table.routes.filter((route) => route.notFound === page || route.error === page).map((route) => route.pattern);
+            problems.push({
+                severity: "error",
+                kind,
+                chain,
+                routes,
+                files: [page],
+                message: `[rivet:router] ${RV_REACH} ${chain.join(" → ")} (server-only), rendered by ${kind === "layout" ? `the layout of every page under ${folder || "/"}` : "an error / not-found page"} (client-rendered on navigation and resume)` +
+                    "\n  fix: read the data in the layout's `load(…)` (or a server-only helper called from it) and render it from props; layouts and error pages cannot be document routes" +
+                    docs,
+            });
+        }
+    // Browser graphs: modules of client-rendered routes (non-document pages, layouts, error pages) vs. document pages only.
+    const closure = (seeds) => {
+        const out = new Set();
+        for (const stack = [...seeds]; stack.length;) {
+            const file = stack.pop();
+            if (out.has(file))
+                continue;
+            out.add(file);
+            for (const target of graph.get(file) ?? [])
+                if (!target.serverOnly)
+                    stack.push(target.key);
+        }
+        return out;
+    };
+    const navigable = closure([...pages.filter((page) => !documents.has(page)), ...layouts, ...specials].map(abs));
+    const documentOnly = new Set([...closure([...documents.keys()].map(abs))].filter((file) => !navigable.has(file)));
+    const targets = new Map(), names = new Map(), chains = new Map();
+    for (const [file, edges] of graph)
+        for (const target of edges) {
+            if (!target.serverOnly)
+                continue;
+            targets.set(file + "\0" + target.spec, target.key);
+            let set = names.get(target.key);
+            if (!set)
+                names.set(target.key, (set = new Set()));
+            for (const name of target.names)
+                set.add(name);
+        }
+    // Stand-in messages: the first document page's chain to each server-only module it reaches.
+    for (const page of documents.keys()) {
+        const file = abs(page);
+        for (const reached of closure([file]))
+            for (const target of graph.get(reached) ?? [])
+                if (target.serverOnly && !chains.has(target.key) && documentOnly.has(reached)) {
+                    const chain = chainFrom(file, false);
+                    chains.set(target.key, chain[chain.length - 1] === (target.key.startsWith("/") ? show(target.key) : target.key) ? chain.slice(0, -1) : [show(file), show(reached)]);
+                }
+    }
+    return { documents, problems, documentOnly, targets, names, chains };
+}
+/** Normalize `rivetRouter({ serverOnly })`. */
+export function serverOnlyOption(option) {
+    if (option === undefined)
+        return { modules: [], reach: "error" };
+    const modules = Array.isArray(option) ? option : (option.modules ?? []);
+    const reach = Array.isArray(option) ? "error" : (option.reach ?? "error");
+    if (!modules.every((pattern) => typeof pattern === "string" || pattern instanceof RegExp))
+        throw new Error("rivetRouter: serverOnly modules must be module ids (strings) or RegExps");
+    if (reach !== "error" && reach !== "warn")
+        throw new Error(`rivetRouter: serverOnly.reach must be "error" or "warn" (got ${JSON.stringify(reach)})`);
+    return { modules, reach };
+}

package/build/routes.d.ts

@@ -7,7 +7,7 @@ export interface RouteModule {
      * handlers), or an endpoint-only plain `x.ts` exporting request handlers.
      */
     readonly server?: string;
-    /** The page module itself declares server exports (`serverLoad`, `onGet`, `prerender`…). */
+    /** The page module itself declares server exports (`load(…)`, `onGet(…)` calls, `prerender`…). */
     readonly inline?: boolean;
     /** Page module with `export const live = true`: its `data` prop is an accessor revalidated in place. */
     readonly live?: boolean;
@@ -40,11 +40,16 @@ export interface RouteTable {
 }
 /**
  * Build the route table from file paths relative to the routes directory (posix separators).
- * `exports`: server export names per module file (`scanRoutes` reads them; pages/layouts with any are
- * `inline`, plain `.ts` files with request handlers are endpoint routes).
+ * `exports`: server export kinds per module file (`load`, `onGet`, … the wrapper names, `?` for a re-export
+ * from a server-only module, plus the flags `prerender` / `live`; `scanRoutes` reads them): pages/layouts
+ * with any are `inline`, plain `.ts` files with a request handler are endpoint routes.
  */
 export declare function routeTable(files: readonly string[], exports?: ReadonlyMap<string, readonly string[]>): RouteTable;
 /** Scan a routes directory and build its table (reads modules for their server exports). */
 export declare function scanRoutes(dir: string): Promise<RouteTable>;
-/** Server export names of route modules (pages, layouts, plain `.ts` files), by file; live pages also list `live`. */
+/**
+ * Server export kinds of route modules (pages, layouts, plain `.ts` files), by file (see `routeTable`);
+ * `prerender` and `live` pages are listed with their flag. Throws on a module whose exports misdeclare the
+ * route (RV3010 untagged magic name, duplicate kind): the file and the compiler's message.
+ */
 export declare function _serverExportsOf(dir: string, files: readonly string[]): Promise<Map<string, string[]>>;

package/build/routes.js

@@ -5,7 +5,8 @@ const PAGE = /\.(tsx|jsx)$/;
 const SERVER = /\.server\.(ts|js)$/;
 /** Plain `.ts`/`.js` route files: endpoint-only routes when they export request handlers. */
 const PLAIN = /\.(ts|js)$/;
-const HANDLER = /^on(Request|Get|Post|Put|Patch|Delete|Options)$/;
+// Request handler kinds; `?` = a re-export from a server-only module (kind known at runtime only).
+const HANDLER = /^(on(Request|Get|Post|Put|Patch|Delete|Options)|\?)$/;
 const IGNORED = /(^|\/)[.]|\.(test|spec)\.[^/]+$|\.d\.ts$/;
 const SPECIAL = new Set(["_layout", "_404", "_error"]);
 /** Parse one path segment of a route file name; null for a path-less `(group)`. */
@@ -43,8 +44,9 @@ const shape = (segments) => "/" + segments.map((s) => (s.kind === "static" ? s.t
 const pattern = (segments) => "/" + segments.map((s) => (s.kind === "static" ? encodeURIComponent(s.text) : (s.kind === "splat" ? "*" : ":") + s.name)).join("/");
 /**
  * Build the route table from file paths relative to the routes directory (posix separators).
- * `exports`: server export names per module file (`scanRoutes` reads them; pages/layouts with any are
- * `inline`, plain `.ts` files with request handlers are endpoint routes).
+ * `exports`: server export kinds per module file (`load`, `onGet`, … the wrapper names, `?` for a re-export
+ * from a server-only module, plus the flags `prerender` / `live`; `scanRoutes` reads them): pages/layouts
+ * with any are `inline`, plain `.ts` files with a request handler are endpoint routes.
  */
 export function routeTable(files, exports = new Map()) {
     const set = new Set(files.filter((file) => !IGNORED.test(file)));
@@ -177,7 +179,15 @@ export async function scanRoutes(dir) {
 const PRERENDER = /^\s*export\s+(?:const|let|var)\s+prerender\b/m;
 // `export const live = true`: a live page (reported as `live`, not a server export; universal, kept in the browser).
 const LIVE = /^\s*export\s+const\s+live\s*=\s*true\b/m;
-/** Server export names of route modules (pages, layouts, plain `.ts` files), by file; live pages also list `live`. */
+// Cheap prefilter (no candidate, no parse): a wrapper import, a server-only re-export, or a former magic name (RV3010).
+const CANDIDATE = /@rivetjs\/router["']|\.server\b|\b(server(Load|Guard|Actions|Entries|Headers)|on(Request|Get|Post|Put|Patch|Delete|Options))\b/;
+// Server-split errors that change what the route table would be: untagged magic names, duplicate kinds.
+const TABLE_ERRORS = /^(Untagged server export|Duplicate server export)/;
+/**
+ * Server export kinds of route modules (pages, layouts, plain `.ts` files), by file (see `routeTable`);
+ * `prerender` and `live` pages are listed with their flag. Throws on a module whose exports misdeclare the
+ * route (RV3010 untagged magic name, duplicate kind): the file and the compiler's message.
+ */
 export async function _serverExportsOf(dir, files) {
     const { moduleFacts } = await import("@rivetjs/compiler");
     const out = new Map();
@@ -186,17 +196,24 @@ export async function _serverExportsOf(dir, files) {
             continue;
         const source = await readFile(join(dir, file), "utf8");
         const live = PAGE.test(file) && LIVE.test(source);
-        // Cheap prefilter: no candidate export name, no parse.
-        const candidates = /\b(server[A-Z]\w*|on(Request|Get|Post|Put|Patch|Delete|Options)|prerender)\b/.test(source);
-        if (!candidates && !live)
+        const prerender = PAGE.test(file) && PRERENDER.test(source);
+        const candidates = CANDIDATE.test(source);
+        if (!candidates && !live && !prerender)
             continue;
-        const names = candidates ? [...(moduleFacts(source, file, { serverExports: true }).serverExports ?? [])] : [];
-        if (PAGE.test(file) && PRERENDER.test(source))
-            names.push("prerender");
+        const kinds = [];
+        if (candidates) {
+            const facts = moduleFacts(source, file, { serverExports: true });
+            const error = facts.serverErrors?.find((e) => TABLE_ERRORS.test(e.message));
+            if (error)
+                throw new Error(`${join(dir, file)}${error.line === null ? "" : `:${error.line}:${error.column ?? 1}`}: ${error.message}`);
+            kinds.push(...(facts.serverKinds ?? []));
+        }
+        if (prerender)
+            kinds.push("prerender");
         if (live)
-            names.push("live");
-        if (names.length)
-            out.set(file, names);
+            kinds.push("live");
+        if (kinds.length)
+            out.set(file, kinds);
     }
     return out;
 }

package/build/vite.d.ts

@@ -9,6 +9,7 @@ export type { InlineStylesheets } from "./route-css.js";
 /** Build-time helper for other Vite plugins (docs-kit example frames): one merged sheet per stylesheet list. */
 export { mergeRouteCSS } from "./route-css.js";
 import { type InlineStylesheets } from "./route-css.js";
+import { type ServerOnlyOption } from "./reach.js";
 import { type AdapterName, type AdapterOptions } from "../adapters/target-build.js";
 /** Options of the `rivetRouter()` Vite plugin. */
 export interface RivetRouterOptions {
@@ -156,6 +157,16 @@ export interface RivetRouterOptions {
     dev?: {
         resume?: boolean;
     };
+    /**
+     * Server-only modules besides `*.server.*` files and modules importing `@rivetjs/router/server-only`: module ids /
+     * specifiers or RegExps (virtual modules serving server data, e.g. `"virtual:docs/api"`; plugins declare theirs as
+     * `api.rivetServerOnly`, `rivet({ serverOnly })` too). Before each build / dev start the router walks every route's
+     * browser graph: a page route reaching one through its own module and plain helper modules is a document route (links
+     * load its document, its module leaves the client build); a component module, layout or error page reaching one fails
+     * the build (RV3011, with the import chain and the routes). `{ modules, reach: "warn" }`: components reaching one only
+     * warn, and the pages rendering them become document routes. Server / static modes (csr keeps the import error).
+     */
+    serverOnly?: ServerOnlyOption;
 }
 /** Router features generated code provides only when the app uses them (`routerUsage`). */
 export interface RouterUsage {
@@ -185,6 +196,8 @@ export declare function routerUsage(root: string, options?: {
 /** Regenerate `.rivet/` for a project root; returns the resume modules and whether files changed. */
 export declare function generateRoutes(root: string, options?: Pick<RivetRouterOptions, "routes" | "outDir" | "document" | "mode" | "transitions" | "announce" | "base" | "searchParams" | "navigate" | "forms" | "params" | "activeLinks" | "trailingSlash" | "prefetch" | "prefetchEagerness" | "prefetchPaths" | "preload" | "routeRules" | "clientRouter"> & {
     head?: "components" | undefined;
+    documents?: readonly string[];
+    derived?: boolean;
 }): Promise<{
     table: RouteTable;
     resumeModules: readonly string[];