Skip to content

Latest commit

 

History

History

client

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 

README.md

@evjs/client

Browser runtime core for standalone CSR apps and the evjs framework.

Features

  • Page Hooks — usePageParams(), usePageSearch(), and usePageLoaderData() expose framework-managed route data while evjs owns route materialization.
  • Standalone CSR — createApp(), createAppRootRoute(), and TanStack Router re-exports support manual browser-only apps without @evjs/ev.
  • SPA Navigation — SPA Pages use evjs page hooks and navigation helpers while the framework owns the route tree and app bootstrap.
  • Router-Free Pages — MPA and framework-managed pages use the page runtime without adding a client router.
  • Data Fetching — Wraps TanStack Query with built-in server function proxies.
  • Server Function Support — useQuery(fn) and useMutation(fn) for typed server-boundary calls.
  • Focused Client API — Standalone/manual client code imports transport, page hooks, navigation helpers, and RSC helpers from @evjs/client; file-convention app source reaches the same authoring APIs through @evjs/ev/route, @evjs/ev/navigation, @evjs/ev/query, and @evjs/ev/transport; generated framework bootstrap uses @evjs/client/internal.

Install

npm install @evjs/client react react-dom

Quick Start

Standalone CSR

Use @evjs/client directly when a browser-only app owns its routing and build pipeline:

import {
  createApp,
  createAppRootRoute,
  createRoute,
  Link,
  Outlet,
} from "@evjs/client";

const rootRoute = createAppRootRoute({
  component: () => (
    <main>
      <Link to="/">Home</Link>
      <Outlet />
    </main>
  ),
});

const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/",
  component: () => <h1>Home</h1>,
});

const app = createApp({
  routeTree: rootRoute.addChildren([indexRoute]),
});

declare module "@evjs/client" {
  interface Register {
    router: typeof app.router;
  }
}

app.render("#app");

An external React host can own the root without creating a hidden or nested DOM root. Component mode returns the same Router, QueryClient, and Application wrappers used by render():

const application = app.createComponent({ signal: mountController.signal });

hostRoot.render(application.element);

// Stop rendering application.element first, then release the ownership token.
application.dispose();

Only one rendering owner may be active. Call app.unmount() before switching from DOM-root mode to component mode, or dispose() before switching back to app.render().

Use @evjs/ev only when the app wants framework composition such as Page routing, server-function transforms, manifests, SSR, PPR, RSC, or deployment artifacts.

Framework-Managed Pages

// src/pages/users/$userId/page.tsx
import { usePageParams } from "@evjs/ev/route";

export default function UserPage() {
  const { userId } = usePageParams();
  return <h1>User {userId}</h1>;
}

usePageParams() is Page-scoped and works across SPA, MPA, and RSC rendering. In an SPA, root and route layouts use useRouteParams() to read the merged params of the active route branch. Native anchors and browser APIs can resolve application routes, including routing.basepath, with useHref() or useHrefResolver() from @evjs/ev/navigation.

Use the page hooks for route data in both SPA and MPA output. They are the zero-annotation path for page code; params, search, and loaderData are not passed as page component props.

Let evjs Build the Application

Framework-managed applications use one Page-and-Route convention. A page.* module is the positive Page/Route anchor; its containing directory owns private source and determines the URL:

// ev.config.ts
import { defineConfig } from "@evjs/ev";

export default defineConfig({
  routing: {
    mode: "spa",
  },
});

The Page directory may contain components, hooks, models, and services without private filename prefixes; those files never become routes. Change only routing.mode to materialize the same semantic Page/Route tree as an MPA. SPA and MPA applications compose the same file-convention layouts. MPA rejects router-only lifecycle and boundary facets.

Explicit application.routes and component/routes config are SPA-only route-tree inputs in @evjs/ev; their converters normalize into the same runtime Page contracts, reject MPA materialization, and do not define additional @evjs/client APIs. File-convention applications use page.tsx for published Pages, keep Page configuration in page.config.ts, and select only routing.mode.

Server Functions

Use the "use server" directive in reachable modules; .server.ts is the recommended naming convention, not a discovery rule. In file-convention apps, import the route data hooks from @evjs/ev/route and query hooks from @evjs/ev/query:

// src/pages/posts/page.tsx
import { useQuery } from "@evjs/ev/query";
import { getPosts } from "../../apis/posts.server";

function Posts() {
  const { data } = useQuery(getPosts);
  return <ul>{data?.map(p => <li key={p.id}>{p.title}</li>)}</ul>;
}

Standalone/manual clients can import the same query hooks directly from @evjs/client when they own the runtime integration.

API

Routing

  • usePageParams: Read framework-managed params from page components.
  • useRouteParams: Read merged params from the active SPA route branch in root and route layouts.
  • usePageSearch and usePageLoaderData: Read framework-managed route data from page components.
  • Link, Navigate, useNavigate, and redirect: Navigation helpers for page components and route lifecycle exports.
  • useHref and useHrefResolver: Resolve application-relative routes to public browser hrefs for native anchors and browser APIs.

Query

  • useQuery(fn, ...args) and useSuspenseQuery(fn, ...args): Call compiler-generated server function stubs with inferred argument and result types.
  • useMutation(fn, options?): Mutate through a compiler-generated server function stub; pass mutationFn only when using the standard TanStack object form.
  • getFnQueryKey(fn, ...args): Generate stable query keys for server functions.
  • getFnQueryOptions(fn, ...args): Generate options for manual queryClient usage.
  • Plain async functions are not server function stubs. Use useQuery({ queryKey, queryFn }) or useMutation({ mutationFn }) for non-server functions.

Transport

  • initTransport({ baseUrl, credentials, headers, functions }): Configure the default HTTP adapter. functions.endpoint can override the server function path for standalone runtimes.
  • credentials / headers: Supported HTTP defaults; fetch mode is intentionally not configurable.
  • Hosting runtimes can set window.__EVJS_TRANSPORT__ before framework server requests run. The value accepts data-only RuntimeTransportOptions: baseUrl, credentials, and headers. Endpoint paths continue to come from framework runtime metadata; application initTransport() calls still take priority for server functions.
  • Runtime transport is for framework-managed browser requests to evjs server endpoints. It is consumed by server functions and RSC Flight. It does not control runtime metadata loading, static assets, dynamic imports, or application-authored fetch() calls.
  • @evjs/client/transport: Public subpath for low-level transport APIs such as createServerReference, getFnId, getFnName, and initTransport.
  • The default HTTP adapter expects successful server-function responses to use Content-Type: application/json. Non-JSON error responses use their trimmed body text for ServerFunctionError, falling back to statusText when the body is empty or only whitespace.
  • initTransport({ adapter }): Replace transport behavior with a custom adapter.
  • Generated server-function stubs use @evjs/client/internal/server-functions; application code should keep using the public transport APIs above.

Runtime

  • Page runtime bootstrap is framework-owned and imported through @evjs/client/internal.
  • Page runtime loads the embedded __EVJS_CLIENT_RUNTIME__ first. Standalone runtimes may explicitly use runtimeUrl or data-evjs-runtime; there is no implicit runtime metadata URL. An external response must be successful JSON with Content-Type: application/json, allowing optional content-type parameters.
  • fetchRscFlight(), createReactRscModel(), mountReactRscPage(), unmountReactRscPage(), and startReactRscPageRuntime(): RSC page runtime helpers for framework-owned Flight and mount flows.
  • RSC page models require successful Flight responses to use Content-Type: text/x-component with optional parameters.
  • Runtime shell primitives such as createShell(), createPageDriver(), and createHistoryDriver() are framework-owned and imported through @evjs/client/internal.
  • Shell activation request URLs must be HTTP(S) URLs or pathnames starting with /.
  • Generated component-page bootstrap APIs are also framework-owned and imported through @evjs/client/internal.

Application-facing client runtime APIs are exported from @evjs/client. Generic TanStack Query APIs that are not paired with evjs server functions should come from @tanstack/react-query. Standalone/manual clients use @evjs/client for evjs page, navigation, server-function, and RSC APIs; normal file-convention app source imports the public authoring surface from @evjs/ev/route, @evjs/ev/navigation, @evjs/ev/query, and @evjs/ev/transport.

License

MIT