react-server

You are working on a project that uses @lazarv/react-server — an open React Server Components runtime (not a framework). It is built on the Vite Environment API and supports Node.js, Bun, and Deno.

Full documentation: https://react-server.dev Any docs page as markdown: https://react-server.dev/{path}.md JSON Schema for configuration: https://react-server.dev/schema.json Examples: https://github.com/lazarv/react-server/tree/main/examples

When you need more detail on a specific topic, fetch the relevant markdown page from the docs site.

CLI Commands

# Development (with explicit entrypoint)
pnpm react-server ./App.jsx

# Development (file-system router, no entrypoint needed)
pnpm react-server

# Production build
pnpm react-server build [./App.jsx]

# Start production server
pnpm react-server start

# Useful flags
# --open          Open browser on start
# --host 0.0.0.0  Listen on all interfaces
# --port 3001     Custom port
# --https         Enable HTTPS

Use Directives

These directives go at the top of a file or inside a function body (lexically scoped RSC):

• "use client" — Client component (enables React hooks, event handlers, browser APIs)
• "use server" — Server function (callable from client, receives FormData as first arg)
• "use live" — Live component (async generator that yields JSX, streams updates via WebSocket)
• "use worker" — Worker module (offloads to Worker Thread on server, Web Worker on client)
• "use cache" — Cached function with options: "use cache; ttl=200; tags=todos" or "use cache; profile=todos" or "use cache: file; tags=todos" or "use cache: request" (per-request dedup) or "use cache: request; no-hydrate" (no browser hydration)
• "use dynamic" — Force dynamic rendering (opt out of static/prerender)
• "use static" — Force static rendering at build time
• "use hydrate" — Hydration island: render a server subtree as HTML immediately, write a separate island RSC payload, and hydrate it later as a local non-root outlet. Syntax: "use hydrate: visible; rootMargin=0px; threshold=0.2; id=counter".

Hydration Islands

Use hydration islands when the page root should stay server-only but a selected subtree needs deferred interactivity. Put the directive inside a server component function body:

function CounterIsland() {
  "use hydrate: visible; rootMargin=0px; threshold=0.2; id=counter";

  return <Counter />;
}

Key behavior:

• The island is SSR-rendered immediately.
• The runtime emits request-scoped hydration data for the island and can omit the main PAGE_ROOT RSC payload when no page-root hydration is needed.
• The client hydrates the island as a local outlet, not as a remote component.
• Hydration islands are created during initial HTML rendering; if a "use hydrate" component appears in a later RSC update payload, it renders as normal React content because the parent tree already owns it.
• Components inside the island can use Link local and Refresh local to navigate or refresh only the island outlet.
• DevTools shows islands in the Outlets panel with an island badge and hydrated/not hydrated state.

Strategies:

• load — hydrate as soon as the client entry runs and the island payload is available. This is the default for "use hydrate" and is best for above-the-fold controls that should become interactive immediately while still using a local outlet.
• idle — hydrate through requestIdleCallback, falling back to setTimeout. Supports timeout in milliseconds; default is 2000.
• visible — hydrate when an IntersectionObserver sees the island marker. Supports rootMargin (default 600px) and threshold (default 0). If IntersectionObserver is unavailable, hydrate immediately.
• interaction — hydrate on user interaction. Default events are pointerenter, focusin, pointerdown, and click; override with events=pointerenter,focusin. The triggering event starts hydration and should not be treated as replayed into the hydrated component.
• media — hydrate when matchMedia(query) matches. If the query already matches, hydrate immediately; otherwise listen for changes. Missing query or unavailable matchMedia falls back to immediate hydration. Use this for motion preferences too, e.g. query=(prefers-reduced-motion: no-preference) or query=(prefers-reduced-motion: reduce).
• never — render static HTML without creating a hydration payload. Client component effects and handlers inside the island never run.

File-System Router Conventions

When no entrypoint is passed to the CLI, the file-system router is used. Default root is src/pages (configurable via root in config).

src/pages/
├── layout.jsx              # Root layout (wraps all routes)
├── page.jsx                # Index page (/)
├── about.jsx               # /about (any .jsx/.tsx file is a page)
├── (group)/                # Route group (no URL segment)
│   └── page.jsx
├── users/
│   ├── page.jsx            # /users
│   ├── [id].page.jsx       # /users/:id (dynamic segment)
│   └── [id]/
│       └── posts.page.jsx  # /users/:id/posts
├── docs/
│   └── [...slug].page.jsx  # /docs/* (catch-all, slug is string[])
├── @sidebar/               # Parallel route / outlet named "sidebar"
│   └── page.jsx
├── loading.page.jsx        # Loading fallback (Suspense boundary)
├── error.page.jsx          # Error fallback (ErrorBoundary)
├── index.middleware.mjs    # Middleware for this route segment
├── GET.posts.server.mjs    # API route: GET /posts
└── mcp.server.mjs          # MCP endpoint at /mcp

Key conventions:

• page.jsx or index.jsx — route page (index route)
• "use client" page — client-only route (no server round-trip, state preserved between navigations)
• layout.jsx — wraps child routes with persistent layout
• [param] — dynamic route parameter (passed as prop)
• [...slug] — catch-all (param is string[])
• [[...slug]] — optional catch-all
• (name) — route group / transparent segment (not in URL)
• @name/ — parallel route outlet
• *.middleware.{js,mjs,ts,mts} — middleware
• *.server.{js,mjs,ts,mts} — API route handler
• GET.*.server.mjs / POST.*.server.mjs — HTTP method-specific API route
• {filename.xml}.server.mjs — escaped route segment for special characters
• *.resource.{js,mjs,ts,mts} — resource file (auto-bound to route)

Route validation (export validate object with params/search schemas from any page):

import { z } from "zod";
import { user } from "@lazarv/react-server/routes";

export const validate = {
  params: z.object({ id: z.string().regex(/^\d+$/) }),
};

export default user.createPage(({ id }) => <h1>User {id}</h1>);

Auto-generated routes module (@lazarv/react-server/routes): exports named route descriptors for every route. Each has .Link, .href(), .useParams(), .useSearchParams(), .createPage(), .createLayout(), .createLoading(), .createError(), .createMiddleware().

Imports Quick Reference

// Core hooks and utilities
import {
  useHttpContext,
  useUrl,
  usePathname,
  useSearchParams,
  useRequest,
  useResponse,
  useFormData,
  headers,
  cookie,
  setCookie,
  deleteCookie,
  status,
  redirect,
  rewrite,
  after,
  useCache,
  useResponseCache,
  withCache,
  revalidate,
  invalidate,
  getRuntime,
} from "@lazarv/react-server";

// Configuration helper
import { defineConfig } from "@lazarv/react-server/config";

// Navigation (client-side)
import { Link, Refresh, ReactServerComponent, ScrollRestoration, useNavigate } from "@lazarv/react-server/navigation";
import { useClient } from "@lazarv/react-server/navigation";
// useClient() returns { navigate, replace, prefetch }

// Typed router
import { createRoute, createRouter, Route, SearchParams } from "@lazarv/react-server/router";

// Resources (typed, schema-validated data fetching)
import { createResource, createResources, resources } from "@lazarv/react-server/resources";

// Auto-generated routes module (file-system router only)
import { index, about, user } from "@lazarv/react-server/routes";

// Error handling
import { ErrorBoundary } from "@lazarv/react-server/error-boundary";

// Client utilities
import { ClientOnly } from "@lazarv/react-server/client";

// Micro-frontends
import RemoteComponent from "@lazarv/react-server/remote";

// Workers
import { isWorker } from "@lazarv/react-server/worker";

// MCP (Model Context Protocol)
import { createServer, createTool, createResource as createMcpResource, createPrompt } from "@lazarv/react-server/mcp";

Typed Router

@lazarv/react-server includes a fully typed routing solution with compile-time type safety for route paths, params, and search params. No code generation step — works with any schema library (Zod, ArkType, Valibot) or lightweight parse functions.

Defining routes with createRoute

import { createRoute } from "@lazarv/react-server/router";
import { z } from "zod";

// Static route
export const home = createRoute("/", { exact: true });

// Dynamic route — params extracted from pattern
export const user = createRoute("/user/[id]", {
  exact: true,
  validate: { params: z.object({ id: z.coerce.number().int().positive() }) },
});

// Search params with validation
export const products = createRoute("/products", {
  exact: true,
  validate: {
    search: z.object({
      sort: z.enum(["name", "price", "rating"]).catch("name"),
      page: z.coerce.number().int().positive().catch(1),
    }),
  },
});

// Lightweight parse (no schema library)
export const post = createRoute("/post/[slug]", {
  exact: true,
  parse: { params: { slug: String }, search: { tab: String } },
});

// Fallback routes
export const notFound = createRoute("*");
export const userNotFound = createRoute("/user/*"); // scoped fallback

Composing routes with createRouter (server)

import { createRoute, createRouter } from "@lazarv/react-server/router";
import * as routes from "./routes";

const router = create

---

*Content truncated.*