@evjs/client
Browser runtime core for standalone CSR apps and the evjs framework.
Features
- Page Hooks —
usePageParams(),usePageSearch(), andusePageLoaderData()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)anduseMutation(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.usePageSearchandusePageLoaderData: Read framework-managed route data from page components.Link,Navigate,useNavigate, andredirect: Navigation helpers for page components and route lifecycle exports.useHrefanduseHrefResolver: Resolve application-relative routes to public browser hrefs for native anchors and browser APIs.
Query
useQuery(fn, ...args)anduseSuspenseQuery(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; passmutationFnonly when using the standard TanStack object form.getFnQueryKey(fn, ...args): Generate stable query keys for server functions.getFnQueryOptions(fn, ...args): Generate options for manualqueryClientusage.- Plain async functions are not server function stubs. Use
useQuery({ queryKey, queryFn })oruseMutation({ mutationFn })for non-server functions.
Transport
initTransport({ baseUrl, credentials, headers, functions }): Configure the default HTTP adapter.functions.endpointcan override the server function path for standalone runtimes.credentials/headers: Supported HTTP defaults; fetchmodeis intentionally not configurable.- Hosting runtimes can set
window.__EVJS_TRANSPORT__before framework server requests run. The value accepts data-onlyRuntimeTransportOptions:baseUrl,credentials, andheaders. Endpoint paths continue to come from framework runtime metadata; applicationinitTransport()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 ascreateServerReference,getFnId,getFnName, andinitTransport.- The default HTTP adapter expects successful server-function responses to use
Content-Type: application/json. Non-JSON error responses use their trimmed body text forServerFunctionError, falling back tostatusTextwhen 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 useruntimeUrlordata-evjs-runtime; there is no implicit runtime metadata URL. An external response must be successful JSON withContent-Type: application/json, allowing optional content-type parameters. fetchRscFlight(),createReactRscModel(),mountReactRscPage(),unmountReactRscPage(), andstartReactRscPageRuntime(): RSC page runtime helpers for framework-owned Flight and mount flows.- RSC page models require successful Flight responses to use
Content-Type: text/x-componentwith optional parameters. - Runtime shell primitives such as
createShell(),createPageDriver(), andcreateHistoryDriver()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