@rivetjs/router 0.0.0-stage → 0.1.0-alpha.1

package/build/routes.js

@@ -0,0 +1,219 @@
+// File-based route table: maps `src/routes/**` files to router patterns, layouts and special pages.
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+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)$/;
+// 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)`. */
+function segment(part, file) {
+    if (/^\([^()/]+\)$/.test(part))
+        return null;
+    let match = /^\[\[([A-Za-z_$][\w$]*)\]\]$/.exec(part);
+    if (match)
+        return { kind: "optional", name: match[1] };
+    match = /^\[\.\.\.([A-Za-z_$][\w$]*)\]$/.exec(part);
+    if (match)
+        return { kind: "splat", name: match[1] };
+    match = /^\[([A-Za-z_$][\w$]*)\]$/.exec(part);
+    if (match)
+        return { kind: "param", name: match[1] };
+    if (/[[\]()*:?#\\]/.test(part))
+        throw new Error(`Invalid route segment "${part}" in ${file}`);
+    return { kind: "static", text: part };
+}
+// Rank per segment: static before param before splat; a route that ends sorts before a splat at
+// the same depth (both match the shorter URL), never against static/param (different lengths).
+const rank = (s) => (s === undefined ? 1.5 : s.kind === "static" ? 0 : s.kind === "splat" ? 2 : 1);
+function compare(a, b) {
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const d = rank(a[i]) - rank(b[i]);
+        if (d)
+            return d;
+        const x = a[i], y = b[i];
+        if (x?.kind === "static" && y?.kind === "static" && x.text !== y.text)
+            return x.text < y.text ? -1 : 1;
+    }
+    return 0;
+}
+const shape = (segments) => "/" + segments.map((s) => (s.kind === "static" ? s.text : s.kind === "splat" ? "*" : ":")).join("/");
+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 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)));
+    const servers = new Map(); // module path without extension → server file
+    for (const file of set)
+        if (SERVER.test(file))
+            servers.set(file.replace(SERVER, ""), file);
+    for (const file of set) {
+        if (SERVER.test(file) || !PLAIN.test(file) || !exports.get(file)?.some((name) => HANDLER.test(name)))
+            continue;
+        const base = file.replace(PLAIN, "");
+        const other = servers.get(base);
+        if (other)
+            throw new Error(`${file} and ${other} are both server modules of ${base}; keep one`);
+        servers.set(base, file);
+    }
+    // `live` (a page flag `_serverExportsOf` reports with them) is not a server export.
+    const isInline = (page) => (page ? (exports.get(page)?.some((name) => name !== "live") ?? false) : false);
+    const isLive = (page) => exports.get(page)?.includes("live") ?? false;
+    const special = (folder, name) => {
+        const base = (folder ? folder + "/" : "") + name;
+        const page = [...set].find((file) => PAGE.test(file) && file.replace(PAGE, "") === base);
+        const server = servers.get(base);
+        return page || server ? { ...(page ? { page } : {}), ...(server ? { server } : {}), ...(isInline(page) ? { inline: true } : {}) } : undefined;
+    };
+    const nearest = (folders, name) => {
+        for (let i = folders.length - 1; i >= 0; i--) {
+            const found = special(folders[i], name)?.page;
+            if (found)
+                return found;
+        }
+        return undefined;
+    };
+    const modules = new Map();
+    for (const file of set) {
+        const page = PAGE.test(file), server = SERVER.test(file) || (PLAIN.test(file) && servers.get(file.replace(PLAIN, "")) === file);
+        if (!page && !server)
+            continue;
+        const base = file.replace(server ? (SERVER.test(file) ? SERVER : PLAIN) : PAGE, "");
+        const name = base.slice(base.lastIndexOf("/") + 1);
+        if (name.startsWith("_")) {
+            if (!SPECIAL.has(name))
+                continue;
+            if (server && name !== "_layout")
+                throw new Error(`${file}: only _layout may have a server module`);
+            continue;
+        }
+        if (base.split("/").some((part) => part.startsWith("_")))
+            continue;
+        const entry = modules.get(base) ?? {};
+        modules.set(base, server ? { ...entry, server: file } : { ...entry, page: file, ...(isInline(file) ? { inline: true } : {}), ...(isLive(file) ? { live: true } : {}) });
+    }
+    const drafts = [];
+    const seen = new Map();
+    for (const [base, module] of [...modules].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        const parts = base.split("/");
+        const folders = [""];
+        for (let i = 0; i < parts.length - 1; i++)
+            folders.push(parts.slice(0, i + 1).join("/"));
+        const parsed = [];
+        for (const [i, part] of parts.entries()) {
+            if (i === parts.length - 1 && part === "index")
+                break;
+            const s = segment(part, base);
+            if (s)
+                parsed.push(s);
+        }
+        const splat = parsed.findIndex((s) => s.kind === "splat");
+        if (splat !== -1 && splat !== parsed.length - 1)
+            throw new Error(`${base}: [...${parsed[splat].name}] must be the last segment`);
+        const names = parsed.flatMap((s) => (s.kind === "static" ? [] : [s.name]));
+        if (new Set(names).size !== names.length)
+            throw new Error(`${base}: duplicate parameter name`);
+        // Each optional segment doubles the variants: with it (longer) and without.
+        let variants = [[]];
+        for (const s of parsed)
+            variants = s.kind === "optional" ? variants.flatMap((v) => [[...v, { kind: "param", name: s.name }], v]) : variants.map((v) => [...v, s]);
+        for (const segments of variants) {
+            const key = shape(segments);
+            const previous = seen.get(key);
+            if (previous !== undefined && previous !== base)
+                throw new Error(`Route conflict: ${previous} and ${base} both match ${key}`);
+            if (previous === base)
+                continue;
+            seen.set(key, base);
+            drafts.push({ id: base, segments, module, folders });
+        }
+    }
+    drafts.sort((a, b) => compare(a.segments, b.segments));
+    const routes = drafts.map(({ id, segments, module, folders }) => {
+        const layouts = folders.map((folder) => special(folder, "_layout")).filter((m) => m !== undefined);
+        const notFound = nearest(folders, "_404"), error = nearest(folders, "_error");
+        return {
+            id,
+            pattern: pattern(segments),
+            params: segments.flatMap((s) => (s.kind === "static" ? [] : [s.name])),
+            ...module,
+            layouts,
+            ...(notFound ? { notFound } : {}),
+            ...(error ? { error } : {}),
+        };
+    });
+    const notFound = special("", "_404")?.page, error = special("", "_error")?.page;
+    // Unmatched URLs: nearest `_404` by folder, for folders without parameters (groups add no segment).
+    const notFounds = [];
+    for (const file of set) {
+        if (!PAGE.test(file) || !file.endsWith("/_404" + file.slice(file.lastIndexOf("."))))
+            continue;
+        const parts = file.split("/").slice(0, -1);
+        if (parts.some((part) => part.startsWith("[")))
+            continue;
+        const prefix = "/" +
+            parts
+                .filter((part) => !/^\(.+\)$/.test(part))
+                .map(encodeURIComponent)
+                .join("/");
+        if (prefix !== "/")
+            notFounds.push({ prefix, page: file });
+    }
+    notFounds.sort((a, b) => b.prefix.length - a.prefix.length || (a.prefix < b.prefix ? -1 : 1));
+    return { routes, ...(notFound ? { notFound } : {}), ...(error ? { error } : {}), ...(notFounds.length ? { notFounds } : {}) };
+}
+/** Scan a routes directory and build its table (reads modules for their server exports). */
+export async function scanRoutes(dir) {
+    const entries = await readdir(dir, { recursive: true, withFileTypes: true });
+    const files = entries.filter((entry) => entry.isFile()).map((entry) => relative(dir, join(entry.parentPath, entry.name)).split(sep).join("/"));
+    return routeTable(files, await _serverExportsOf(dir, files));
+}
+// `export const prerender` alone also makes a page carry server exports (a plain flag).
+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;
+// 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();
+    for (const file of files) {
+        if (IGNORED.test(file) || SERVER.test(file) || !(PAGE.test(file) || PLAIN.test(file)))
+            continue;
+        const source = await readFile(join(dir, file), "utf8");
+        const live = PAGE.test(file) && LIVE.test(source);
+        const prerender = PAGE.test(file) && PRERENDER.test(source);
+        const candidates = CANDIDATE.test(source);
+        if (!candidates && !live && !prerender)
+            continue;
+        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)
+            kinds.push("live");
+        if (kinds.length)
+            out.set(file, kinds);
+    }
+    return out;
+}

package/build/sync.d.ts

@@ -0,0 +1,20 @@
+export interface SyncOptions {
+    /** App root (default the current directory). */
+    root?: string;
+    /** Vite config file (default: Vite's lookup in `root`). */
+    configFile?: string;
+    /** Vite mode (default `production`). */
+    mode?: string;
+}
+export interface SyncResult {
+    root: string;
+    /** Vite config file used (undefined: none found, nothing generated). */
+    configFile: string | undefined;
+    /** The written editor manifest, or null when no Rivet plugin ran. */
+    manifest: {
+        resumeModules?: string[];
+        routesDir?: string;
+        routes?: unknown[];
+    } | null;
+}
+export declare function sync({ root, configFile, mode }?: SyncOptions): Promise<SyncResult>;

package/build/sync.js

@@ -0,0 +1,16 @@
+// `rivet sync`: write an app's generated `.rivet/` files (route types, generated app, editor
+// manifest) without starting Vite. Resolves the app's own Vite config, so every plugin option
+// (routes dir, resume modules, base, i18n…) applies exactly as in `vite` / `vite build`: the router
+// plugin's `config` hook regenerates `.rivet/`, the compiler plugin's `configResolved` hook writes
+// `.rivet/editor.json`. Run it before `tsc` / `rivet-check` on a fresh clone (`.rivet/` is gitignored).
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+export async function sync({ root = process.cwd(), configFile, mode = "production" } = {}) {
+    const { resolveConfig } = await import("vite");
+    const appRoot = resolve(root);
+    const config = await resolveConfig({ root: appRoot, mode, logLevel: "warn", ...(configFile ? { configFile: resolve(appRoot, configFile) } : {}) }, "build", mode);
+    const manifest = await readFile(resolve(config.root, ".rivet/editor.json"), "utf8")
+        .then((text) => JSON.parse(text))
+        .catch(() => null);
+    return { root: config.root, configFile: config.configFile, manifest };
+}

package/build/vite.d.ts

@@ -0,0 +1,208 @@
+import type { Plugin } from "vite";
+import { type ImagesConfig, type RivetCSSOptions, type RivetOptions, type RivetResumeOptions } from "@rivetjs/compiler/vite";
+import { type RouteTable } from "./routes.js";
+import { type CodegenOptions } from "./codegen.js";
+import { type TrailingSlash } from "../shared/slash.js";
+import { type RouteRules } from "../server/route-cache.js";
+import type { DocumentPrefetch, PrefetchEagerness } from "../shared/prefetch.js";
+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 {
+    /** Routes directory, root-relative (default `src/routes`). */
+    routes?: string;
+    /**
+     * URL base path the app is served under (`/app`); sets Vite's `base`. Default: Vite's `base`.
+     * Route patterns, `<Link to>`, `navigate()`, data requests, prefetch and the adapters follow it.
+     */
+    base?: string;
+    /**
+     * Trailing-slash policy. `"ignore"` (default): `/a` and `/a/` serve the same page as requested.
+     * `"never"` / `"always"`: one canonical form — page GET/HEAD requests for the other answer 308,
+     * `<Link>` / `navigate()` write hrefs in it, the static adapter writes `a.html` (`never`) or
+     * `a/index.html`. `/` itself never changes; endpoints and other methods are never redirected.
+     */
+    trailingSlash?: TrailingSlash;
+    /**
+     * Preload planner default for this app's pages (`createApp` / adapter `preload` options override it per server):
+     * `background` = byte budget (minified closures) of below-the-fold `visible` chunks also prefetched at idle; `0` off.
+     * Default 1 MiB. Dev pages keep `visible` chunks viewport-only (dev manifests have no bundle sizes).
+     */
+    preload?: {
+        background?: number;
+    };
+    /**
+     * Route rules by path pattern (`/about`, `/blog/*`, `/docs/**`): `headers`, and `cache` / `swr` / `isr` — rendered pages
+     * stored in process (fresh for `maxAge` s, then served stale while one render refreshes them; `isr: true` until
+     * `revalidate()`), with ETag / Last-Modified → 304 and `s-maxage` / `stale-while-revalidate` for CDNs. JSON data:
+     * the server entry exports it, every adapter applies it (`createApp` / adapter `routeRules` replace it). Dev applies
+     * `headers` only. See `@rivetjs/router/route-cache`.
+     */
+    routeRules?: RouteRules;
+    /** Codegen output directory, root-relative (default `.rivet`). */
+    outDir?: string;
+    /** Root-relative module whose default export is the `DocumentShell` (default `src/document.ts`). */
+    document?: string;
+    /** Root-relative stylesheets: client build inputs, linked by the document (`styles`). */
+    styles?: string[];
+    /**
+     * Stylesheets written into the page as `<style>` instead of linked (Astro's `build.inlineStylesheets`), production
+     * server / static pages, decided per page. `"auto"` (default): all of the page's sheets (global + route) when their
+     * brotli sizes add up to at most 6 KB (the page then has no render-blocking stylesheet request), else each sheet of
+     * at most Vite's `build.assetsInlineLimit` (4096 raw bytes; a function limit counts as 4096). `{ maxTotalBrotli }`:
+     * `auto` with another total (bytes). `"always"`: every sheet; `"never"`: all linked. Sheets with relative `url()` /
+     * `@import` references stay linked. Inline styles carry the page's CSP nonce (static pages: hashed into a
+     * `style-src` you set).
+     */
+    inlineStylesheets?: InlineStylesheets;
+    /** `server` (default) and `static` resume server-rendered pages; `csr` mounts a single-page app. */
+    mode?: NonNullable<CodegenOptions["mode"]>;
+    /** Resume options; generated route modules are added to `modules`. */
+    resume?: Partial<RivetResumeOptions>;
+    /** `?image` / `?jsx` imports (`rivet({ images })`); build with the app builder so server-only images reach the client output. */
+    images?: ImagesConfig | true;
+    /** DevTools on the dev server when `@rivetjs/devtools` is installed (default true; see `rivet()`). */
+    devtools?: boolean;
+    /**
+     * Framework bridges (`rivet({ bridges })`: `react()` from `@rivetjs/bridge-react/vite`, `preact()` from
+     * `@rivetjs/bridge-preact/vite`, …): those frameworks' components render as islands inside the routed pages.
+     * Server / static modes only.
+     */
+    bridges?: RivetOptions["bridges"];
+    /**
+     * Component head (`@rivetjs/kit` `<Title>`, `<Meta>`, …): `components` holds each page's document
+     * start until its shell rendered; on by default when the kit Vite plugin (`kit()`) is installed.
+     * `early` keeps route `head` exports only (document start written first).
+     */
+    head?: "components" | "early";
+    /** Scoped styles options passed to `rivet({ css })`. */
+    css?: RivetCSSOptions;
+    /** Compile-time `<Icon>` from `@rivetjs/kit/icon` (`rivet({ staticIcons })`, default true); `false` keeps every component call. */
+    staticIcons?: boolean;
+    /**
+     * Route transitions (View Transitions) + pending UI. Off by default; `true` = defaults. The
+     * transitions module loads on the first navigation intent; the generated resume entry provides
+     * the navigation context (a custom `resume.entry` must add `[Navigation, navigation]` itself).
+     */
+    transitions?: CodegenOptions["transitions"];
+    /** Route announcer for screen readers after client navigation (default true; `false` opts out). */
+    announce?: boolean;
+    /**
+     * The app reads search params (`useSearchParams()` / `SearchParams`): the server provides the
+     * request's, the resume entry the browser's. Default: detected from the project's sources
+     * (`routerUsage`); set `true` when only a published dependency reads them.
+     */
+    searchParams?: boolean;
+    /** The app calls `navigate()` / `invalidate()` / `revalidate()` / `setSearchParams()`. Default: detected (`routerUsage`). */
+    navigate?: boolean;
+    /**
+     * The app uses `@rivetjs/forms` (directly or through `@rivetjs/ui` `Form`): enhanced submits reach the router
+     * through `Symbol.for("rivet.router")` (implies `navigate`). Default: detected (`routerUsage`).
+     */
+    forms?: boolean;
+    /** The app reads `useParams()`. Default: detected (`routerUsage`). */
+    params?: boolean;
+    /** The app renders `<Link active>`: active links are re-marked after client navigation. Default: detected (`routerUsage`). */
+    activeLinks?: boolean;
+    /**
+     * Document prefetch for navigations that load a document (`@rivetjs/router/prefetch`): every page's
+     * head gets Speculation Rules (Chromium) + a ~1 kB inline intent fallback. `"document"` / `"prerender"`:
+     * also the default for every same-origin link without its own `prefetch` / `data-rivet-prefetch`
+     * (plain `<a>` included; `"none"` opts one out). `true`: only links marked `prefetch="document"` /
+     * `"prerender"`. Default: detected (`routerUsage`: such a mark in the sources); `false`: off.
+     * Server / static modes (ignored in `csr`).
+     */
+    prefetch?: boolean | DocumentPrefetch;
+    /**
+     * When Chromium starts a document prefetch / prerender (Speculation Rules `eagerness`):
+     * `"conservative"` (pointer / touch down), `"moderate"` (default: also a ~200 ms hover), `"eager"`
+     * (sooner). Applies only while `prefetch` is on; the fallback keeps its 65 ms / focus / down timing.
+     */
+    prefetchEagerness?: PrefetchEagerness;
+    /**
+     * Which links of a client-routed app take part in document prefetch. Default `true`: `data-rivet-reload` /
+     * `rel=external` links and links whose path no route matches (every page carries the route-path RegExp, in the
+     * Speculation Rules and in the fallback call). `false`: only `data-rivet-reload` / `rel=external` links — for apps
+     * whose document links all carry `reload` (the docs sites: −7.7 KB of route patterns per page).
+     */
+    prefetchPaths?: boolean;
+    /**
+     * Client-side navigation on pages with nothing else to resume (Astro's `<ClientRouter />` model).
+     * `true`: every resumed page ships the router (link clicks / intent prefetch / back-forward served in
+     * place). `false`: the router's listeners alone do not make a page resumable — a page without resumable
+     * symbols, client effects or forms ships zero JS (no loader, state script or modulepreloads) and its
+     * links load documents; interactive pages still route in place. Default: `false` in `static` mode,
+     * `true` in `server` mode (ignored in `csr`).
+     */
+    clientRouter?: boolean;
+    /**
+     * Deploy target besides node (name or options object): `vite build --ssr` also emits the target's
+     * entry (client manifests inlined, dependencies bundled). `"fetch"`: `dist/server/fetch.js`
+     * (`export default { fetch }`, any web-standard runtime). Platforms, packaged after the server build:
+     * `"vercel"` (`.vercel/output`, Build Output API v3), `"netlify"` (`.netlify/v1` + `dist/netlify`),
+     * `"cloudflare"` (`dist/cloudflare`, Workers + static assets), `"bun"` (`dist/server/bun.js`),
+     * `"deno"` (`dist/server/deno.js`).
+     */
+    adapter?: AdapterName | AdapterOptions;
+    /**
+     * Dev server. `resume` (default true): pages resume like production (recorder state, inline loader,
+     * symbol chunks served by Vite); the first hot update switches the page to client rendering, after
+     * which components hot-replace in place. `false`: pages client-render over the server HTML (the
+     * recorder still runs, so serialization errors still reach the overlay).
+     */
+    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 {
+    /** `useSearchParams` / `SearchParams`. */
+    searchParams: boolean;
+    /** `navigate` / `invalidate` / `revalidate` / `setSearchParams`, or forms (below). */
+    navigate: boolean;
+    /** `@rivetjs/forms`, or `Form` in a file importing `@rivetjs/ui` (its `Form` is built on forms). */
+    forms: boolean;
+    /** `useParams`. */
+    params: boolean;
+    /** `<Link active>` (an `active` attribute on a `<Link>`). */
+    activeLinks: boolean;
+    /** `prefetch="document"` / `"prerender"` (`<Link>` prop or `data-rivet-prefetch` attribute). */
+    prefetch: boolean;
+}
+/**
+ * Which router features the project's sources use: every source under `root` (skipping
+ * `node_modules`, `dist` and dot directories) plus the sources of linked (workspace / `npm link`)
+ * dependencies of `root/package.json`, except `@rivetjs/*` packages. Text based: a name that appears
+ * in a file importing `@rivetjs/router` counts (false positives only cost bytes); published
+ * dependencies are not scanned (set `rivetRouter({ navigate, params, searchParams })`).
+ */
+export declare function routerUsage(root: string, options?: {
+    exclude?: readonly string[];
+}): Promise<RouterUsage>;
+/** 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[];
+    changed: boolean;
+    resumeEntry: boolean;
+}>;
+/** The router's Vite plugins: file routes, typed routes, server code split, data requests and build adapters. */
+export declare function rivetRouter(options?: RivetRouterOptions): Plugin[];