# @axiomhq/tanstack-start 中文文档

规范地址：https://npmcn.com/package/%40axiomhq/tanstack-start/

版本：0\.2\.0
npm 元数据更新时间：2026-09-03T13:21:03.302Z
中文译文更新时间：2026-11-07T16:29:46.394Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40axiomhq/tanstack-start
原文对照：https://npmcn.com/package/%40axiomhq/tanstack-start/?lang=original
项目主页：https://github.com/axiomhq/axiom-js/blob/main/packages/tanstack-start/README.md
源码仓库：https://github.com/axiomhq/axiom-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：237 kB，58 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：react \>=18，solid-js \>=1\.8，@axiomhq/logging 0\.3\.0，@tanstack/router-core \>=1，@tanstack/start-client-core \>=1
- 首次发布：2026-05-06T15:44:48.598Z
- 最新版本发布：2026-06-29T11:10:17.874Z
- 近 30 天下载量：4879（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

Axiom 的官方 TanStack Start 软件包

## 安装

```sh
npm install @axiomhq/tanstack-start
```

也可以使用：`pnpm add @axiomhq/tanstack-start`、`yarn add @axiomhq/tanstack-start`、`bun add @axiomhq/tanstack-start`

## README

# Axiom TanStack 启动

这个 `@axiomhq/tanstack-start` 软件包为TanStack Start跨React和Solid的应用程序提供可观察性帮助.

## 安装

```bash
npm install @axiomhq/js @axiomhq/logging @axiomhq/tanstack-start
```

## 软件包表面

### 根: 共享 TanStack 启动核心

使用根包进行框架中性启动可观察性 :

-   `createAxiomRequestMiddleware`
-   `createAxiomFnMiddleware`
-   `createAxiomFnCorrelationMiddleware`
-   `createAxiomProxyHandler`
-   `createAxiomUncaughtErrorHandler`
-   `captureError`
-   `getLogLevelFromStatusCode`
-   `getStartErrorStatusCode`
-   `transformStartRequestSuccessResult`
-   `transformStartRequestErrorResult`
-   `transformStartFunctionSuccessResult`
-   `transformStartFunctionErrorResult`
-   `tanStackStartServerFormatters`
-   `tanStackStartClientFormatters`

```ts
import {
  createAxiomFnMiddleware,
  createAxiomRequestMiddleware,
  tanStackStartServerFormatters,
} from '@axiomhq/tanstack-start';
```

### `@axiomhq/tanstack-start/router`

使用 TanStack 路由器导航和计时辅助工具的明确的路由器子路径 :

-   `observeTanStackRouter`
-   `tanStackRouterFormatters`

```ts
import { observeTanStackRouter, tanStackRouterFormatters } from '@axiomhq/tanstack-start/router';
```

### `@axiomhq/tanstack-start/react`

使用 React 适配器报告 TanStack 路由器的错误 `defaultErrorComponent`按路线 `errorComponent`,或更广泛的应用级边界 :

```ts
import { createAxiomReactErrorHandler } from '@axiomhq/tanstack-start/react';
```

### `@axiomhq/tanstack-start/solid`

使用 Solid 适配器报告 TanStack 路由器的错误 `defaultErrorComponent`按路线 `errorComponent`,或更广泛的应用级边界 :

```ts
import { createAxiomSolidErrorHandler } from '@axiomhq/tanstack-start/solid';
```

## 锁定设置

```ts
import { Logger, ConsoleTransport } from '@axiomhq/logging';
import { tanStackStartServerFormatters } from '@axiomhq/tanstack-start';
import { tanStackRouterFormatters } from '@axiomhq/tanstack-start/router';

export const routerLogger = new Logger({
  transports: [new ConsoleTransport()],
  formatters: tanStackRouterFormatters,
});

export const startLogger = new Logger({
  transports: [new ConsoleTransport()],
  formatters: tanStackStartServerFormatters,
});
```

接收日志附件的 TanStack 启动助手 `axiom-tanstack-start/<version>` 用于支持的伐木运输工具 `X-Axiom-Client` 头曰.

## 共享启动中端软件

Start中相软件API是框架中立的,因为它们建立在TanStack Start核心合同上.

```ts
import {
  createAxiomFnMiddleware,
  createAxiomRequestMiddleware,
} from '@axiomhq/tanstack-start';

export const requestMiddleware = [
  createAxiomRequestMiddleware(startLogger, {
    include: ['/api/*', '/_server/*'],
    exclude: ['/api/health'],
  }),
];

export const functionMiddleware = [
  createAxiomFnMiddleware(startLogger, {
    correlation: true,
  }),
];
```

请求和函数中间软件正在等待 `logger.flush()` 在解决之前。 当我们以后想要无阻送货时 干净的路就是引入注射器 `waitUntil`\- 原始的,而不是扩大 公共配置表面.

每个服务器函数使用一个函数仪表路径. 若为 `createAxiomFnMiddleware` 全球通过 `createStart({ functionMiddleware })`,不同时将其附加到单个服务器函数中,除非您有意为同一调用需要多个日志事件.

为充分定制所排放的字段或副作用,提供 `onSuccess` 编号 : `onError` 召回电话。 当提供回调时,中间软件跳过该路径的默认日志. 这个 `transformStart*Result` 为想要保留默认信件/报告形状并添加自己字段的用户导出帮助器 .

```ts
import {
  createAxiomRequestMiddleware,
  getLogLevelFromStatusCode,
  getStartErrorStatusCode,
  transformStartRequestErrorResult,
  transformStartRequestSuccessResult,
} from '@axiomhq/tanstack-start';

export const requestMiddleware = [
  createAxiomRequestMiddleware(startLogger, {
    onSuccess: async (data) => {
      const [message, report] = transformStartRequestSuccessResult(data);
      const logLevel = getLogLevelFromStatusCode(data.response.status);

      startLogger.log(logLevel, message, {
        ...report,
        tenant: data.request.headers.get('x-tenant-id'),
        region: data.request.headers.get('x-region'),
      });

      await startLogger.flush();
    },
    onError: async (data) => {
      const [message, report] = transformStartRequestErrorResult(data);
      const logLevel = getLogLevelFromStatusCode(getStartErrorStatusCode(data.error));

      startLogger.log(logLevel, message, {
        ...report,
        tenant: data.request.headers.get('x-tenant-id'),
        region: data.request.headers.get('x-region'),
      });

      await startLogger.flush();
    },
  }),
];
```

```ts
import {
  createAxiomFnMiddleware,
  transformStartFunctionErrorResult,
  transformStartFunctionSuccessResult,
} from '@axiomhq/tanstack-start';

export const functionMiddleware = [
  createAxiomFnMiddleware(startLogger, {
    correlation: true,
    onSuccess: async (data) => {
      const [message, report] = transformStartFunctionSuccessResult(data);

      startLogger.info(message, {
        ...report,
        requestHeaders: {
          tenant: data.context.context?.request?.headers.get('x-tenant-id'),
          region: data.context.context?.request?.headers.get('x-region'),
        },
      });

      await startLogger.flush();
    },
    onError: async (data) => {
      const [message, report] = transformStartFunctionErrorResult(data);

      startLogger.error(message, {
        ...report,
        requestHeaders: {
          tenant: data.context.context?.request?.headers.get('x-tenant-id'),
          region: data.context.context?.request?.headers.get('x-region'),
        },
      });

      await startLogger.flush();
    },
  }),
];
```

对于简单的副作用,回调可以完全忽略日志:

```ts
createAxiomRequestMiddleware(startLogger, {
  onSuccess: async (data) => {
    await analytics.track('request_complete', {
      path: new URL(data.request.url).pathname,
      statusCode: data.response.status,
    });
  },
});
```

## 路由器观察员

```ts
import { observeTanStackRouter } from '@axiomhq/tanstack-start/router';

const observe = observeTanStackRouter(routerLogger, {
  source: 'tanstack-router-spa',
  performance: true,
});

const unsubscribe = observe(router);
```

`observeTanStackRouter` 听着 `onResolved` 默认。 它只在浏览器中订阅,所以从同样运行于SSR期间的路由器设置中拨打是安全的. 回来的 `unsubscribe` 函数可以被HMR或自定义路由器生命周期所使用.

使用默认 `source` 联 合 国 `tanstack-router` 一般路由器仪表,或设置自定义源,例如 `tanstack-router-spa`, (中文(简体) ), `tanstack-router-react`,或 `tanstack-router-solid` 当您想要区分 Axiom 中的应用/框架变体时.

何时 `performance` 除导航日志外,还启用了观察员对路由器生命周期事件和路径定时日志.

## 客户端- Side 代理摄入

对于浏览器日志, 使用 `ProxyTransport` 并接收与客户 `createAxiomProxyHandler` 在服务器上。 这保留了 Axiom 令牌服务器侧面,同时保留了客户端代码中相同的logger API.

```ts
// src/lib/axiom/client.ts
import { ConsoleTransport, Logger, ProxyTransport } from '@axiomhq/logging';
import type { Transport } from '@axiomhq/logging';
import { tanStackStartClientFormatters } from '@axiomhq/tanstack-start';
import { tanStackRouterFormatters } from '@axiomhq/tanstack-start/router';

function createBrowserTransports(): [Transport, ...Transport[]] {
  return [
    new ProxyTransport({ url: '/api/axiom' }),
    new ConsoleTransport({ prettyPrint: true }),
  ];
}

export const routerLogger = new Logger({
  transports: createBrowserTransports(),
  formatters: tanStackRouterFormatters,
});

export const clientLogger = new Logger({
  transports: createBrowserTransports(),
  formatters: tanStackStartClientFormatters,
});
```

```ts
// src/lib/axiom/server.ts
import { Axiom } from '@axiomhq/js';
import { AxiomJSTransport, ConsoleTransport, Logger } from '@axiomhq/logging';
import { tanStackStartServerFormatters } from '@axiomhq/tanstack-start';

const axiom = new Axiom({ token: process.env.AXIOM_TOKEN! });

export const startLogger = new Logger({
  transports: [
    new AxiomJSTransport({
      axiom,
      dataset: process.env.AXIOM_DATASET!,
    }),
    new ConsoleTransport({ prettyPrint: true }),
  ],
  formatters: tanStackStartServerFormatters,
});
```

```ts
// src/routes/api/axiom.ts
import { createFileRoute } from '@tanstack/react-router';
import { createAxiomProxyHandler } from '@axiomhq/tanstack-start';
import { startLogger } from '../../lib/axiom/server';

const proxyHandler = createAxiomProxyHandler(startLogger);

export const Route = createFileRoute('/api/axiom')({
  server: {
    handlers: {
      POST: ({ request }) => proxyHandler(request),
    },
  },
});
```

对于 Solid 应用程序, 使用相同的路径模式 `createFileRoute` 从 `@tanstack/solid-router`。 。 。 .

## 客户端出错边界

TanStack Start的内置模式是用 TanStack 路由器捕捉路径渲染和加载器出错 `defaultErrorComponent` 或路线 `errorComponent`。下面的适配器被设计为首先插入该边界模型.

### 反应

```ts
import { ErrorComponent, createRouter, type ErrorComponentProps } from '@tanstack/react-router';
import { useEffect } from 'react';
import { createAxiomReactErrorHandler } from '@axiomhq/tanstack-start/react';

const handleClientError = createAxiomReactErrorHandler(startLogger);

function RouterErrorBoundary({ error, reset }: ErrorComponentProps) {
  useEffect(() => {
    handleClientError(error);
  }, [error]);

  return <ErrorComponent error={error} />;
}

const router = createRouter({
  routeTree,
  defaultErrorComponent: RouterErrorBoundary,
});
```

### 固态

```tsx
import { ErrorComponent, createRouter, type ErrorComponentProps } from '@tanstack/solid-router';
import { onMount } from 'solid-js';
import { createAxiomSolidErrorHandler } from '@axiomhq/tanstack-start/solid';

const handleClientError = createAxiomSolidErrorHandler(startLogger);

function RouterErrorBoundary(props: ErrorComponentProps) {
  onMount(() => handleClientError(props.error, props.reset));
  return <ErrorComponent error={props.error} />;
}

const router = createRouter({
  routeTree,
  defaultErrorComponent: RouterErrorBoundary,
});
```

如果您还想要在 TanStack 路由器路由界限外捕获客户端错误, 您仍然可以从一个更广泛的框架级边界使用相同的适配器帮助器 .

## 覆盖率

SDK 备份 :

-   请求中间软件
-   服务器功能中间软件
-   请求/功能关联
-   路由器导航日志
-   路由器计时日志
-   代理摄取
-   未发现服务器输入抓取
-   React and Solid 客户端错误边界帮助器

仅供用户使用:

-   健康检查
-   调试信头
-   专门针对环境的伐木政策

## 实例

-   反应 : [`examples/tanstack-start`](https://npmcn.com/package/examples/tanstack-start)
-   固态 : [`examples/tanstack-start-solid`](https://npmcn.com/package/examples/tanstack-start-solid)

## 移徙说明

路由仪现在被故意明确。 导入路由器帮助器 `@axiomhq/tanstack-start/router` 而不是根包.

## 许可证

[麻省理工学院](https://npmcn.com/package/LICENSE)

## 常见问题

### @axiomhq/tanstack-start 是什么？

Axiom 的官方 TanStack Start 软件包

### 如何安装 @axiomhq/tanstack-start？

在项目目录运行 npm install @axiomhq/tanstack-start，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@axiomhq/logging（0\.3\.0）、@tanstack/router-core（\>=1）、@tanstack/start-client-core（\>=1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @axiomhq/tanstack-start 支持 TypeScript 吗？

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

### @axiomhq/tanstack-start 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @axiomhq/tanstack-start 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @axiomhq/tanstack-start 可以商用吗？

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

### @axiomhq/tanstack-start 的下载量有多少？

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

### @axiomhq/tanstack-start 还在维护吗？

最新版本 0\.2\.0 发布于 2026/06/29（4 个月前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/05/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。