# test_tokui_react

**Repository Path**: jboltai_main/test_tokui_react

## Basic Information

- **Project Name**: test_tokui_react
- **Description**: TokUI React demo案例工程
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TokUI · React 18 流式渲染集成案例

> 后端用极简 DSL 描述组件，经 **SSE 流式推送**，前端基于 [TokUI](https://tokui.jboltai.com) 增量解析、**首个 Token 即开始渲染**。

本仓库演示如何把 `@jboltai/tokui` 接入 React 18 + Vite 工程，并配一个零依赖的 Node SSE 推流 server，完整跑通「DSL 碎片 → 流式渲染」全链路。

## 截图

<!-- TODO: 截图占位 —— 截一张「开始推送」后双栏（左渲染 / 右 DSL 源码高亮）的运行画面，放入下方路径后提交。 -->

![TokUI 运行截图](docs/screenshot.png)

## 特性

- ⚡ **首 Token 即渲染** —— DSL 逐片到达、增量解析，不等流结束。
- 🧩 **80+ 组件大满贯** —— 基础、表单、数据展示、反馈、导航、图表、代码 七大类全覆盖。
- 🖱️ **双向联动** —— 点击右侧 DSL 代码行，左侧实时定位对应组件（fixed 定位框跟随）。
- 🎨 **DSL 语法高亮** —— 参考官网 Playground，关键字 / 值 / 字符串 / 注释分色。
- 🔌 **零依赖生产 Server** —— 纯 Node `http`，无任何运行时依赖，自带安全加固。
- 🛡️ **安全开箱即用** —— Origin 白名单、并发上限、body 限长、目录穿越防护、SPA 兜底。

## 技术栈

| 层 | 选型 |
|----|------|
| 渲染框架 | [TokUI](https://www.npmjs.com/package/@jboltai/tokui) `@jboltai/tokui` |
| 前端 | React 18 + Vite 5 + TypeScript |
| 推流协议 | SSE（`text/event-stream`） |
| 生产 Server | 纯 Node `node:http`（零依赖） |

## 快速开始

```bash
# 1. 安装依赖
npm install

# 2a. 开发模式（Vite dev + 内置 SSE 中间件）
npm run dev

# 2b. 生产构建
npm run build

# 3. 启动生产 server（托管 dist/ + /api/stream）
npm start
# → http://127.0.0.1:5632
```

打开页面后点击 **「开始推送」**，DSL 将经 SSE 流式推送、左侧逐步渲染、右侧实时显示带行号的源码碎片。

> 端口提示：`server.js` 默认 `PORT=5632`，与同机的 `test_tokui_vue` 冲突。同时跑两版时，React 版用 `PORT=5633 npm start`。两个 dev server 各占独立 5173 不冲突。

## 项目结构

```
.
├── src/
│   ├── App.tsx        # 主界面：渲染舞台 + DSL 源码面板 + 行→组件联动
│   ├── main.tsx       # React 入口，挂载 TokUI CSS
│   ├── style.css      # 全局样式
│   └── env.d.ts
├── dsl.mjs            # SSE 推送的 DSL 碎片（dev 与 server 共用）
├── server.js          # 生产 server：静态托管 + /api/stream（零依赖）
├── vite.config.ts     # Vite 配置 + dev SSE 中间件 + TokUI 版本注入
└── package.json
```

## 工作原理

```
浏览器 ──POST /api/stream──▶ Node server
       ◀──text/event-stream──
          data: {"tokui":"[h1 ...]"}
          data: {"tokui":"[btn ...]"}
          ...
          data: [DONE]
              │
              ▼
        TokUI.feed(chunk)   # 增量解析，首 Token 即渲染
```

- `dsl.mjs` 导出 `FULL_DSL` 与 `fragmentize()`，被 `vite.config.ts`（dev）与 `server.js`（prod）共用，保证两端推流逻辑一致。
- 自适应步进：按碎片总数把总推送时长压到 ~9s（每片 5~18ms）。

## 生产部署（server.js 环境变量）

| 变量 | 默认 | 说明 |
|------|------|------|
| `HOST` | `127.0.0.1` | 监听地址。默认仅本机 / Nginx 反代可达 |
| `PORT` | `5632` | 端口 |
| `ALLOWED_ORIGINS` | _空_ | 允许的前端 Origin，逗号分隔。**生产必填**，留空=开放模式（会打警告） |
| `MAX_STREAMS` | `50` | 同时 SSE 连接上限（防连接耗尽） |
| `MAX_BODY` | `8192` | POST body 字节上限 |

```bash
ALLOWED_ORIGINS=https://tokui-react.jboltai.com PORT=5632 node server.js
```

## 相关链接

- 🌐 TokUI 官网 / Playground：<https://tokui.jboltai.com>
- 📦 npm：<https://www.npmjs.com/package/@jboltai/tokui>
- 🐙 GitHub：<https://github.com/jboltai/tokui>
- 📘 DSL 语法参考：<https://tokui.jboltai.com/guide/dsl-syntax>

## 声明

由 [JBoltAI 团队](https://jboltai.com)开源贡献。