@evjs/client

中文文档
0.3.31发布于 2026/11/16MITTypeScriptES Module构建来源已验证近 30 天下载 2757

Client-side runtime for the evjs framework

原始使用文档
文档目录13 节
  1. Features
  2. Install
  3. Quick Start
  4. Standalone CSR
  5. Framework-Managed Pages
  6. Let evjs Build the Application
  7. Server Functions
  8. API
  9. Routing
  10. Query
  11. Transport
  12. Runtime
  13. License

@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

版本与发布记录

@evjs/client 共发布 100 个版本,首次发布于 2026/03/24;过去 12 个月发布了 100 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.3.31latest2026/11/16今天
0.3.302026/11/141 天前
0.3.30-alpha.1alpha2026/11/123 天前
0.3.30-alpha.02026/11/114 天前
0.2.18legacy2026/11/0214 天前
0.3.292026/11/0115 天前

关于 @evjs/client 的常见问题

@evjs/client 是什么?

Client-side runtime for the evjs framework

如何安装 @evjs/client?

在项目目录运行 npm install @evjs/client,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=18.0.0)、react-dom(>=18.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@evjs/client 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@evjs/client 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@evjs/client 可以商用吗?

@evjs/client 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@evjs/client 的下载量有多少?

根据 npm 官方下载统计,@evjs/client 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,757 次,日均约 92 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@evjs/client 还在维护吗?

最新版本 0.3.31 发布于 2026/11/16(今天);至今共发布 100 个版本,其中过去 12 个月发布了 100 个;首次发布于 2026/03/24。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。