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

package/package.json

@@ -1,6 +1,158 @@
 {
   "name": "@rivetjs/router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.1",
+  "description": "File routing for Rivet: loaders, actions, guards, a web-standard request handler, Node / static / edge adapters.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "rivet": "./cli/rivet.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./server": {
+      "types": "./server/index.d.ts",
+      "default": "./server/index.js"
+    },
+    "./route-cache": {
+      "types": "./server/route-cache.d.ts",
+      "default": "./server/route-cache.js"
+    },
+    "./server-only": {
+      "types": "./server-only.d.ts",
+      "default": "./server-only.js"
+    },
+    "./client": {
+      "types": "./client/index.d.ts",
+      "development": "./client/dev.js",
+      "default": "./client/index.js"
+    },
+    "./route-context": {
+      "types": "./client/route-context.d.ts",
+      "default": "./client/route-context.js"
+    },
+    "./leave": {
+      "types": "./client/leave.d.ts",
+      "default": "./client/leave.js"
+    },
+    "./navigation": {
+      "types": "./client/navigation.d.ts",
+      "default": "./client/navigation.js"
+    },
+    "./search": {
+      "types": "./client/search.d.ts",
+      "default": "./client/search.js"
+    },
+    "./transitions": {
+      "types": "./client/transitions.d.ts",
+      "default": "./client/transitions.js"
+    },
+    "./prefetch": {
+      "types": "./shared/prefetch.d.ts",
+      "default": "./shared/prefetch.js"
+    },
+    "./link": {
+      "types": "./client/link.d.ts",
+      "default": "./client/link.jsx"
+    },
+    "./transitions.css": "./client/transitions.css",
+    "./tailwind.css": "./client/tailwind.css",
+    "./routes": {
+      "types": "./build/routes.d.ts",
+      "default": "./build/routes.js"
+    },
+    "./node": {
+      "types": "./adapters/node.d.ts",
+      "default": "./adapters/node.js"
+    },
+    "./fetch": {
+      "types": "./adapters/fetch.d.ts",
+      "default": "./adapters/fetch.js"
+    },
+    "./static": {
+      "types": "./adapters/static.d.ts",
+      "default": "./adapters/static.js"
+    },
+    "./csr": {
+      "types": "./adapters/csr.d.ts",
+      "default": "./adapters/csr.js"
+    },
+    "./vercel": {
+      "types": "./adapters/vercel.d.ts",
+      "default": "./adapters/vercel.js"
+    },
+    "./vercel-edge": {
+      "types": "./adapters/vercel-edge.d.ts",
+      "default": "./adapters/vercel-edge.js"
+    },
+    "./netlify": {
+      "types": "./adapters/netlify.d.ts",
+      "default": "./adapters/netlify.js"
+    },
+    "./cloudflare": {
+      "types": "./adapters/cloudflare.d.ts",
+      "default": "./adapters/cloudflare.js"
+    },
+    "./bun": {
+      "types": "./adapters/bun.d.ts",
+      "default": "./adapters/bun.js"
+    },
+    "./deno": {
+      "types": "./adapters/deno.d.ts",
+      "default": "./adapters/deno.js"
+    },
+    "./head": {
+      "types": "./shared/head.d.ts",
+      "default": "./shared/head.js"
+    },
+    "./vite": {
+      "types": "./build/vite.d.ts",
+      "default": "./build/vite.js"
+    }
+  },
+  "dependencies": {
+    "@rivetjs/runtime": "0.1.0-alpha.1",
+    "@rivetjs/reactivity": "0.1.0-alpha.1",
+    "@rivetjs/compiler": "0.1.0-alpha.1"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "peerDependencies": {
+    "vite": "^8.3.2"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/N1XUS/rivetjs.git",
+    "directory": "libs/router"
+  },
+  "homepage": "https://github.com/N1XUS/rivetjs/tree/main/libs/router#readme",
+  "bugs": {
+    "url": "https://github.com/N1XUS/rivetjs/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "adapters",
+    "build",
+    "cli",
+    "client",
+    "index.d.ts",
+    "index.js",
+    "server",
+    "server-only.d.ts",
+    "server-only.js",
+    "shared"
+  ]
+}

package/server/app.d.ts

@@ -0,0 +1,175 @@
+import type { ServerValue } from "@rivetjs/runtime/server";
+import type { ResumeManifest } from "@rivetjs/runtime/server-resume";
+import type { RenderCache } from "@rivetjs/runtime/server-cache";
+import type { ActionResult, Head, HeadSink, LoaderDeps } from "../shared/data.js";
+import { type CSPOptions } from "../shared/csp.js";
+import { type InlineStyleManifest } from "./inline-styles.js";
+import type { TrailingSlash } from "../shared/slash.js";
+import { type AppHandler, type AppRoute, type BodyLimit, type ErrorInfo, type ShellPhase } from "./handler.js";
+import { type DocumentShell } from "./render.js";
+import type { EarlyHintsOptions } from "./early-hints.js";
+import type { RouteCacheOptions, RouteRules } from "./route-cache.js";
+/** How a dev page renders (`AppConfig.devResume`). */
+export type DevResumeMode = "check" | "resume";
+/** What the generated page factory receives. */
+export interface PageInput {
+    readonly data: readonly unknown[];
+    readonly url: URL;
+    readonly head: Head | undefined;
+    readonly error?: {
+        readonly status: number;
+        readonly message: string;
+    };
+    /** Component head collector (entries generated with `@rivetjs/kit`); the app provides it through `ServerData`. */
+    readonly headSink?: HeadSink;
+    /** The form action this request performed (no-JS POST): pages read it with `actionResult()`. */
+    readonly action?: ActionResult;
+    /** Layouts whose loader read the request URL (client navigation reloads them on any URL change). */
+    readonly byURL?: readonly number[];
+    /** Loaders' `event.depends()` keys (absent when none called it): resumed with the layout state for `invalidate(key)`. */
+    readonly deps?: LoaderDeps;
+    /** A `data` slot is a deferred loader's handle (`load(fn, { defer: true })`): the page streams (out of order) even without `stream`. */
+    readonly deferred?: true;
+    /** A deferred loader's redirect target, read at the document's end (client redirect). */
+    readonly moved?: () => string | undefined;
+    /** @internal Route rule `shell`: a shell fill / replay (always streams). */
+    readonly shell?: ShellPhase;
+}
+/** Shape of the generated `.rivet/entry.server.tsx` module. */
+export interface GeneratedEntry {
+    readonly routes: readonly AppRoute[];
+    readonly universal: Readonly<Record<string, () => Promise<[number, {
+        head?: unknown;
+    }][]>>>;
+    page(input: PageInput): () => ServerValue;
+    /** The app's document shell, when codegen was given one. */
+    readonly document?: DocumentShell;
+    /** `createApp` from the same bundle as the app (one runtime instance). */
+    readonly createApp?: typeof createApp;
+    /** Generated with component head (`@rivetjs/kit`): pages hold the document start until the shell rendered. */
+    readonly headComponents?: boolean;
+    /** URL base path the route patterns carry (`""` or e.g. `/app`; `rivetRouter({ base })` / Vite `base`). */
+    readonly base?: string;
+    /** `rivetRouter({ trailingSlash })` when `"never"` / `"always"` (the handler's 308s use the bundle's build-time constant; the static adapter reads this). */
+    readonly trailingSlash?: Exclude<TrailingSlash, "ignore">;
+    /** `rivetRouter({ preload: { background } })`: the default `preload.background` of this app's pages. */
+    readonly preloadBackground?: number;
+    /** Document prefetch on (`rivetRouter({ prefetch })`): the default `preload.ahead` of this app's pages. */
+    readonly fetchAhead?: boolean;
+    /** `rivetRouter({ routeRules })`: the app's route rules (JSON data; `createApp({ routeRules })` replaces them). */
+    readonly routeRules?: RouteRules;
+}
+/** Config of the server app built from the generated routes entry. */
+export interface AppConfig {
+    readonly entry: GeneratedEntry;
+    /** Document shell; defaults to the entry's `document`. */
+    readonly document?: DocumentShell;
+    /** Stylesheet URLs passed to the document. */
+    readonly styles?: readonly string[];
+    /**
+     * Per-route stylesheets (route modules' CSS), linked after `styles`: the client build's
+     * `.vite/rivet-route-css.json` (see `loadBuild`) or, in dev, a lookup of the route's module graph.
+     */
+    readonly routeStyles?: Readonly<Record<string, readonly string[]>> | ((routeId: string) => readonly string[] | Promise<readonly string[]>);
+    /**
+     * Stylesheets pages may write inline instead of linking: the client build's `.vite/rivet-inline-css.json`
+     * (`rivetRouter({ inlineStylesheets })`, see `loadBuild`), decided per page from its `styles` + `routeStyles` list
+     * (`inlineStylesFor`). Dev links every sheet.
+     */
+    readonly inlineStyles?: InlineStyleManifest;
+    /** Document defaults below every route (level −1): e.g. `{ titleTemplate: "%s · Shop", meta: [...] }`. */
+    readonly head?: Head;
+    /** Production resume manifest; omit in dev (see `devResume`). */
+    readonly manifest?: ResumeManifest;
+    readonly dev?: boolean;
+    /**
+     * Dev (no manifest): module scripts that client-render the page (e.g. the Vite client and the
+     * generated `entry.dev.tsx`). The app renders inside `[data-rivet-dev]` with its route data embedded.
+     * A function gets the page's locale (i18n), e.g. to load that locale's dev module graph.
+     */
+    readonly devScripts?: readonly string[] | ((locale: string | undefined) => readonly string[]);
+    /**
+     * Dev server (`rivetRouter` sets it; no production `manifest`): pages render through the resume
+     * recorder with this dev manifest, so serialization and chunk errors surface as in production.
+     * `mode` (per page locale when a function): `"check"` leaves the recorded state and loader out of
+     * the page and the browser client-renders (`devScripts`, embedded data); `"resume"` serves the
+     * page resumable like production, inside `[data-rivet-dev="resume"]` followed by `devScripts`.
+     */
+    readonly devResume?: {
+        readonly manifest: ResumeManifest;
+        readonly mode: DevResumeMode | ((locale: string | undefined) => DevResumeMode);
+    };
+    readonly stream?: {
+        deadline?: number;
+    };
+    /**
+     * Preload planner. `background`: byte budget (minified) of `visible` chunks' static closures also prefetched at idle,
+     * in plan order (default 1 MiB, `0` off; Save-Data / 2G never). A function decides per page URL (`undefined`: default),
+     * e.g. `0` for embedded frames that a page shows many of. `lean` (per page URL when a function): nothing loads before
+     * the first interaction — no scheduled prefetch (eager / idle / visible / background) and no router fetch-ahead;
+     * handlers load on intent (pointer dwell, focus, touch) and interaction, as under Save-Data.
+     */
+    readonly preload?: {
+        readonly background?: number | ((url: URL) => number | undefined);
+        readonly lean?: boolean | ((url: URL) => boolean | undefined);
+        /**
+         * Islands-only lean pages of a file-router app (bridge D-lean: the router's region + link listeners deferred until
+         * the first link intent / click) still fetch the runtime + router chunks ahead (low priority after `load`, fetched,
+         * never evaluated). On `resume.chunks: "route"` builds every page also fetches its own handler chunks ahead the
+         * same way. Default: the app's document prefetch (`rivetRouter({ prefetch })` on → true). Ignored with `lean`.
+         */
+        readonly ahead?: boolean;
+    };
+    /**
+     * Content-Security-Policy for HTML pages, given the response's nonce (inline scripts carry it).
+     * Default: strict nonce policy (`strictCSP`); `CSPOptions` (`{ trustedTypes, directives }`): `strictCSP` with them (directives checked at startup);
+     * `false` sends none. A `headers()` CSP wins.
+     */
+    readonly csp?: false | CSPOptions | ((nonce: string) => string);
+    /** Server failures (`digest` set for 5xx responses, matching the message the client sees; `phase`/`route` where it failed). */
+    onError?(error: unknown, request: Request, info?: ErrorInfo): void;
+    /**
+     * i18n: locales in compiler variant order and per-locale resume manifests. A page renders the
+     * variant and manifest of `locals.locale` (set by a guard, e.g. `i18nGuard`); `locals.dir` reaches
+     * the document as `dir`. Error pages use the request's `locals` too; without a locale there
+     * (unmatched URLs, guards that failed first) `resolve(request)` decides, else a first path segment
+     * naming a locale, else the first locale.
+     */
+    readonly i18n?: {
+        readonly locales: readonly string[];
+        readonly manifests?: Readonly<Record<string, ResumeManifest>>;
+        resolve?(request: Request): string | undefined | Promise<string | undefined>;
+    };
+    /** Request body limit for unsafe methods (413 past it); default 1 MiB, multipart 10 MiB. */
+    readonly maxBody?: BodyLimit;
+    /**
+     * Route rules by path pattern (`{ "/blog/**": { swr: 60 }, "/about": { isr: true, headers: { … } } }`): response headers,
+     * and an in-process cache of rendered pages (fresh, stale-while-revalidate, ISR; ETag / Last-Modified → 304).
+     * Defaults to the entry's (`rivetRouter({ routeRules })`). The rules module loads only when there are rules.
+     * See `server/route-cache.ts` / docs "Caching".
+     */
+    readonly routeRules?: RouteRules;
+    /** The route rules' page store: `maxBytes` (default 32 MiB), `maxEntries` (default 5000), `origin` (the public origin pages are stored for; `isr` needs it). */
+    readonly routeCache?: RouteCacheOptions;
+    /**
+     * Cross-request fragment cache (`createRenderCache()` from `@rivetjs/runtime/server-cache`): every page renders inside
+     * its scope (`withRenderCache`: locale variant, nonce, abort signal, resumable), so `cached()` / `shell()` / compiler
+     * `_cached` components hit across requests. Node-only (AsyncLocalStorage; Workers: `nodejs_als`); loaded only when set.
+     */
+    readonly renderCache?: RenderCache;
+    /**
+     * Early hints for HTML pages (production only): linked stylesheets, the head's build-asset font preloads (learned
+     * per route from its last render), `links` (e.g. preconnects), and with `runtime: true` the resume runtime entry. Sent as `103 Early
+     * Hints` by the node adapter before guards and loaders run (`start({ earlyHints })`), and as a `Link` header on every
+     * page response (proxies such as Cloudflare turn it into 103s). Browsers act on 103s over HTTP/2+ only. Pages served
+     * from the route cache get the stored `Link` header but no 103 (no render runs): it helps uncached pages. Default off.
+     */
+    readonly earlyHints?: boolean | EarlyHintsOptions;
+}
+/**
+ * Merge heads outer → inner: inner wins per key (title; meta by name/property/http-equiv/itemprop
+ * + media; one canonical; alternates by hreflang; other links by rel + href; scripts by id/src).
+ */
+export declare function mergeHeads(heads: readonly (Head | undefined)[]): Head | undefined;
+/** Create the app's request handler. */
+export declare function createApp(config: AppConfig): AppHandler;