DOCSEARCHbyAlgolia
Submit Docs

@lazarv/react-server Documentation

repository·main·Indexed 19 days ago

https://github.com/lazarv/react-server

A high-performance React framework designed to run on Node.js, Bun, and Deno. It supports Server Components, Hydration Islands, and Live Components. The framework includes a CLI tool (@lazarv/create-react-server) for project bootstrapping and a flexible adapter architecture for deploying to various cloud platforms and runtimes via Node or Edge modes.

Tokens
229K
Snippets
724
Records
959
Agent score
65%

What's inside @lazarv/react-server

  1. Overview of @lazarv/react-server features

    main

    @lazarv/react-server is a runtime providing tools and utilities for building server-side rendered (SSR) React applications. It is built on top of Vite and offers a comprehensive suite of features for modern web development, including:

    • Core Rendering: Server Components, Client Components, Hydration Islands, and Partial Pre-rendering (PPR).
    • Data & State: Server Functions (with AES-256-GCM encryption), Caching (in-memory or custom providers), and Live Components for real-time streaming updates via the "use live" directive.
    • Concurrency & Offloading: Workers using the "use worker" directive to run heavy computations in Node.js Worker Threads (server) or Web Workers (client) with transparent RSC serialization.
    • Architecture Patterns: File-system routing, Micro-frontends (via RemoteComponent), and Middleware mode for integration with existing servers like Express or NestJS.
    • Developer Experience: Built-in DevTools for inspecting RSC payloads, cache, and server logs, plus OpenTelemetry integration for observability.
    • AI Integration: Support for Model Context Protocol (MCP) to expose server-side functions and tools to language models.

  2. What is @lazarv/rsc?

    main

    @lazarv/rsc is a bundler-agnostic and environment-agnostic React Server Components (RSC) serialization and deserialization library. It implements the React Flight protocol without direct dependencies on the react package or specific bundler globals.

    Key Characteristics

    • Bundler-agnostic: No Webpack or Vite plugins required; users provide their own moduleResolver or moduleLoader.
    • Environment-agnostic: Built on Web Platform APIs (ReadableStream, WritableStream, FormData, etc.), making it compatible with Node.js, Deno, Bun, Cloudflare Workers, and browsers.
    • Full Flight Parity: Supports Elements, Promises, Map, Set, Date, BigInt, RegExp, Symbol, URL, FormData, and more.

  3. Overview of the @lazarv/react-server Router

    main

    The @lazarv/react-server runtime provides a fully typed router designed for compile-time type safety across routes, links, parameters, and search parameters. It supports several routing paradigms:

    • Typed Routing: Use createRoute and createRouter to enable typed Link components, typed hooks, schema validation, and IDE autocompletion on both server and client.
    • File-System Routing: A built-in router that automatically uses the file system. When using the react-server CLI, simply omit the entrypoint to enable automatic file-system routing.
    • Third-Party Integration: You can replace the built-in router with solutions like React Router or TanStack Router.

    Routes can be configured as server-rendered, client-only, or shared between environments.

  4. Explore the @lazarv/react-server API Reference

    main

    The @lazarv/react-server API is organized into several functional subpaths. Documentation for these symbols is auto-generated from TypeScript definitions, ensuring that the API reference matches the types available in your editor.

    Key API groups include:

    Runtime

    • Core (@lazarv/react-server): HTTP context hooks, cookie helpers, caching utilities, and rendering controls.
    • Client (@lazarv/react-server/client): Navigation, refresh, and prefetching contexts, plus the ClientOnly component.
    • Router (@lazarv/react-server/router): Typed routing primitives, route factories, and schema validators.
    • Navigation (@lazarv/react-server/navigation): <Link>, <Form>, <Refresh>, <ReactServerComponent>, and navigation hooks.

    Data, Rendering, & Resiliency

    • Resources (@lazarv/react-server/resources): createResource and createResources for binding validated data loaders to routes.
    • Remote Components (@lazarv/react-server/remote): Loading remote React components from other deployments.
    • Error Boundary (@lazarv/react-server/error-boundary): Catching rendering errors in server components.
    • Prerender (@lazarv/react-server/prerender): Partial pre-rendering controls via usePrerender and withPrerender.
    • Function (@lazarv/react-server/function): Server-function validation and Flight protocol helpers (e.g., formData, file, stream).

    Caching

    • Memory Cache (@lazarv/react-server/memory-cache): Default in-memory provider.
    • Storage Cache (@lazarv/react-server/storage-cache): Durable backends using unstorage (Redis, Cloudflare KV, etc.).
    • RSC (@lazarv/react-server/rsc): Low-level serialization for React server component payloads.

    Config, Build, & Deploy

    • Config (@lazarv/react-server/config): ReactServerConfig for react-server.config.mjs.
    • Adapters (@lazarv/react-server/adapters/*): Shared types for deployment adapters.
    • Node (@lazarv/react-server/node): Mounting the runtime in Express, Fastify, or NestJS.
    • Dev/Build (@lazarv/react-server/dev, @lazarv/react-server/build): Programmatic entry points for development and build pipelines.

  5. Compare @lazarv/react-server with other frameworks

    main

    This documentation provides a feature comparison between @lazarv/react-server and other React frameworks like Next.js, TanStack Start, React Router, and Waku. It evaluates them across several dimensions: full-stack features, architecture, routing, type safety, search parameters, scroll restoration, data fetching, and developer experience.

    Legend for comparison:

    • ✅ First-class, built-in support: Documented and part of the intended model.
    • 🟡 Partial support: Important limitations or narrow use cases.
    • 🔶 Possible through userland: Requires manual setup or community plugins.
    • 🛑 No meaningful built-in support.

  6. Security responsibilities of the host

    main

    While @lazarv/rsc provides a hardened serialization and deserialization engine, the following security measures must be implemented by the host application:

    • Authentication & Authorization: The decoder does not check if a user is allowed to call a specific server reference. You must implement authorization (e.g., via middleware) around your reply endpoints.
    • Transport Integrity: The decoder does not sign or encrypt payloads. For bound-argument encryption, use the feature provided by @lazarv/react-server.
    • Request Rate Limiting: Resource ceilings protect against single large decodes, but you must implement rate limiting on your reply endpoints to prevent high-volume request attacks.

  7. Virtual module addressing and resolution

    main

    Extracted components and functions are identified using virtual module IDs that utilize URL query parameters to encode the extraction chain.

    Query Parameter Syntax

    Virtual IDs follow standard URL query syntax to avoid ambiguity:

    • The first parameter is introduced by ?.
    • Subsequent parameters are separated by &.

    Example IDs:

    • file.jsx?use-client-inline=Counter
    • file.jsx?use-client-inline=Counter&use-server-inline=increment (In this case, the last parameter determines the module's identity: it is a "use server" module).

    Relative Import Resolution

    Because virtual module IDs contain query parameters, standard filesystem resolvers cannot find them. The system handles this by intercepting relative imports (starting with ./ or ../) from a virtual module and stripping the query parameters from the importer to resolve the actual filesystem path via the standard resolver.

    // Example of virtual module ID encoding an extraction chain
// The last parameter defines the module type
const id = "file.jsx?use-client-inline=Counter&use-server-inline=increment";

  8. Configure the Router for Layouts, Pages, and Advanced Routing

    main

    The router allows you to define the structure of your application using various routing patterns:

    • Route Types: Define layouts, pages, nested routes, dynamic routes, and catch-all routes.
    • Outlets: Create reusable application parts that can be injected into different layouts.
    • Error & Loading States: Implement dedicated components for error handling and loading states within the routing lifecycle.
    • API & Middleware: Create API route handlers and middlewares using the same file-system rules used for pages and layouts.
    • Content Types: Use Markdown or MDX files directly as pages for static content.
    • Static Site Generation: Combine the router with the runtime to generate a static website, including non-page files like sitemap.xml.

  9. Understand the @lazarv/react-server Adapter Architecture

    main

    An adapter packages a built @lazarv/react-server application for a specific deployment target (e.g., a cloud platform or runtime). The build pipeline follows these stages:

    1. Server build: Generates RSC + SSR bundles in .react-server/server/*.mjs.
    2. Client build: Generates client component bundles in .react-server/client/*.mjs.
    3. Manifest: Generates route and component manifests in .react-server/*-manifest.json.
    4. Edge build (optional): Bundles the server into a single edge.mjs file (no node_modules required).
    5. Static export (optional): Pre-renders HTML into .react-server/dist/.
    6. Adapter: The final step where the adapter copies or transforms the build output into the target's expected layout.

  10. Understand the @lazarv/react-server architectural layers

    main

    @lazarv/react-server is designed as a layered runtime where each layer provides guarantees to the layer above it. Understanding this hierarchy helps in understanding how execution, application structure, and deployment interact.

    The layers are:

    1. Execution Foundation: Defines the core execution environment and the rendering pipeline.
    2. Execution Extensions: Introduces additional execution contexts on top of the foundation.
    3. Application Model: Shapes how applications are structured using the underlying execution layers.
    4. Operational Model: Governs how the application behaves in deployment and production environments.

  12. Compare Azure Functions vs. Azure Static Web Apps

    main

    Choosing between the azure (Functions v4) and azure-swa (Static Web Apps) adapters depends on your requirements for streaming and asset delivery.

    Featureazure (Functions v4)azure-swa (Static Web Apps)
    StreamingYesNo (responses are buffered)
    Static filesServed by the functionServed by CDN
    Auto-provisioningYes (via Bicep)Manual (portal or CLI)
    Cold startsConsumption plan latencyManaged by SWA
    Custom domainsVia Function App settingsVia SWA settings
    Functions versionv4 (programming model)v3 (function.json)

    Use azure if: You need response streaming (React Suspense, progressive HTML) or want automatic resource provisioning. Use azure-swa if: You have a static-heavy app and want CDN-backed asset serving.