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

package/build/vite.d.ts

@@ -0,0 +1,195 @@
+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 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;
+    };
+}
+/** 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;
+}): 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[];