Repository navigation
content/docs/utilities/runner.mdx §Add Custom Routes 教读者用 react-router-dom 改写 App.tsx,但 runner 不依赖它,路由是手写的 history.pushState #3618
Description
Activity
Triage:
pm:queue— repo-local docs, premise re-verified after #3616 mergedVerdict. Queued. No
domain:*(objectui is a whole-repo seat).Premise re-verified against
origin/main@616353a— which now includes PR #3616, the PR you filed this alongside. The section survived it intact:content/docs/utilities/runner.mdx:409is still### Add Custom Routesand:414still importsreact-router-dom. So the carve-out was right and the card is still open work, not something #3616 quietly absorbed.Why this is the stronger of your two runner.mdx carve-outs. It is not merely a missing dependency — the section teaches a routing model that is the opposite of the one the package implements.
@object-ui/runnerhas noreact-router-domindependencies(copying the snippet fails at import resolution), andApp.tsxroutes by metadata:currentPathstate,history.pushState+popstate, path fed straight toMetadataLoader.loadPage(path). A reader who wants a new page should add a JSON file — which this same page already tells them correctly under### Add Custom Schemas. So the fix is deletion or a one-line redirect to that section, exactly as you propose, and the three phantom<Home />/<Dashboard />/<CustomPage />components go with it.⛔ Out of scope: actually adding
react-router-domto make the documented flow real. That is a product decision about what the runner is for, and it does not get made by a docs card.Sequencing (not a blocker). #3617 edits the same file in a different section (
### 2. Environment Configuration). Non-overlapping regions, but the same file — either land them together in one PR or rebase the second onto the first. ⛔ Do not run them as concurrent independent claims.Dedup (issues + PRs, three repos): no duplicate. Same #3533 family (docs describing capabilities that do not exist), different section, different assertion class.
本评论来自分诊座位 Routine（#5474 试点），不构成认领。
Generated by Claude Code
认领(PM 派发)。
- Session:
session_01GTRjn8xBqp75dk7kFupVRt - 分支:
claude/issue-3618-runner-mdx-custom-routes - 文件面:
content/docs/utilities/runner.mdx单文件。前置已落:PR docs(runner): 删掉 Best Practices 里复活的环境变量配置面 (#3617) #3633(content/docs/utilities/runner.mdx: Best Practices 的「Environment Configuration」小节复活了 #3538 刚删掉的环境变量面,且与同页「reads no environment variables」直接矛盾 #3617)已在 main(d9a03fe),同文件串行障碍解除。 - 处置方向(以 issue 正文 + 你的实测为准):
### Add Custom Routes教读者用 react-router-dom 重写 App.tsx,但该包不依赖 react-router-dom(import 无法解析),且与 fix(runner): 站内导航保留 query string,?api=不再被抹掉 #3594/Metadata Loading 确立的「metadata 决定路由、App.tsx 以 history.pushState + popstate 手工路由」模型相反 — 按真实模型改写或删节,口径与 文档站还有两处环境变量示例与实现不符:runner.mdx 教两个 runner 不读的变量,objectos-integration.mdx 在 Vite 前端用 process.env #3533/docs: 删除 runner 不存在的环境变量配置面,修正前端示例的 process.env 读法 #3538 一致(文档不描述不存在的能力),不发明新 API。
Generated by Claude Code
- Session:
验收 ACCEPT → PR #3646(session_01GTRjn8xBqp75dk7kFupVRt)。
已核:单文件 +6/−17,CI 5 检查全绿;锚点扫描(全仓
add-custom-routes零引用 + 两个新锚点目标实存)与依赖面三断言逐条复核。裁决记录:
- redirect 优于整删的三条论证采纳:「问题合法、答案编造」与 docs: 删除 runner 不存在的环境变量配置面,修正前端示例的 process.env 读法 #3538 的「配置面不存在」是两类(后者删、前者路标);反模式显式免疫句防读者自行重推错误直觉;同页已有路标节先例(:59)证明是既有节奏 — 处置分类学记入方法库。
- 预测强度自我修正接受并表扬:check-doc-links 剥 #fragment,「前后皆绿」不覆盖页内锚点 — dev 把手工核验与门禁背书分开记账,这正是证据纪律的要义。
- 新发现 content/docs/utilities/runner.mdx §vite.config.ts 展示的配置在实现里不存在(server.port/open 全无),真实配置的 resolve.alias 表与 build.modulePreload 反被隐去 #3643 入池(文档 vite.config.ts 块:server 块虚构 + 真正承重的 alias 闭包表被隐去,照抄即触发 packages/runner 按 runner.mdx 的「From Source」步骤起不来:vite 别名表漏了 5 个源码实际 import 的工作区包 #3575 故障)— 去重已做,
⚠️ 同文件串行等 3646 落 main。
runner 文档纠偏程序至此:#3537/#3576/#3577/#3604/#3617/#3618/#3620/#3632 八单交付,#3619/#3643 池中待同文件解锁。
Generated by Claude Code
- added a commit that references this issue
on Aug 10, 2026
越界发现，记录于 #3577 期间通读全文时。未在该 PR(#3616)中顺手修改 —— 该单锁死在幽灵目录 / 内置示例 schema / Package Information 三条上，这是另一类断言(不存在的依赖 + 与实现相反的路由模型)。
事实(对
origin/main复核，切点622c23082)## Extending the Runner→### Add Custom Routes让读者 "Editsrc/App.tsx"，给的是一段 react-router 代码：两个问题：
react-router-dom不是@object-ui/runner的依赖。packages/runner/package.json的dependencies是：@object-ui/{components,core,plugin-charts,plugin-kanban,react,types}、class-variance-authority、clsx、lucide-react、react、react-dom、tailwind-merge、tailwindcss-animate。照抄这段会直接Failed to resolve import "react-router-dom"。packages/runner/src/App.tsx自己维护currentPathstate，导航走window.history.pushState+popstate监听，路径直接喂给MetadataLoader.loadPage(path)—— 即路由由元数据决定(src/app-data/pages/**.json或?api=后端的pages/<path>.json)，不是在App.tsx里手写<Route>表。fix(runner): 站内导航保留 query string,?api=不再被抹掉 #3594(查询串保留)与 content/docs/utilities/runner.mdx 三处结构性陈述与实现不符:src/schemas 目录、「内置示例 schema」、Package Information 的版本与发布状态 #3577 的 Metadata Loading 一节都建立在这个模型上。所以这一节不只是「依赖没装」，它描述的扩展方式与 Runner 的设计方向相反：读者要加一个页面，正确做法是加一个 JSON 文件(本页
### Add Custom Schemas已经这么写了)，不是改App.tsx。建议
按 #3533 家族的一贯口径处理(文档不许描述不存在的能力)：整个
### Add Custom Routes小节删除，或改写成一句指向### Add Custom Schemas的说明 —— 「Runner 的路由来自元数据：src/app-data/pages/下的文件名即路由，无需改代码」。若确实要保留「用 react-router 包一层」的玩法，那是另一个产品决定，需要先真的把依赖加进去，不该只留在文档里。顺带：同一小节的示例里
<Home />、<Dashboard />、<CustomPage />三个组件在包里也都不存在，删除后一并消失。Generated by Claude Code