From ea19faa2fe0e5317c1e1ab0d6b1ec19c48f5ab55 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 7 Aug 2026 16:08:01 +0000 Subject: [PATCH] =?UTF-8?q?docs(runner):=20README=20=C2=A7Development=20Wo?= =?UTF-8?q?rkflow=20=E6=8C=89=E4=B8=A4=E4=B8=AA=20loader=20=E7=9A=84?= =?UTF-8?q?=E7=9C=9F=E7=9B=B8=E6=94=B9=E5=86=99=E7=AC=AC=201=E3=80=813=20?= =?UTF-8?q?=E6=AD=A5=20(#3604)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 第 1 步「Create a schema file (JSON or TypeScript)」与本文件自己的 §Metadata Loading 直接矛盾:runner 没有任何路径能加载 TypeScript 写的 schema —— LocalBundleLoader 的三个 import.meta.glob 全是 `.json` (MetadataLoader.ts:26-28),NetworkLoader 只 fetch 固定的 `.json` 路径 并直接 `res.json()`(同文件 89、101 行)。按 #3533 的口径(文档不许描述 实现里不存在的能力)改写成 JSON 的两条真实路线,并点名 `src/app-data/` 是 git-ignored、新检出下不存在、仓里没有任何脚本会创建它 —— 这正是照旧 文本操作的读者下一步会撞上的坑(每次加载返回 null,页面渲染成 404)。 第 3 步「changes reload automatically」按 loader 分路限定而非删除: `src/app-data/` 下的 JSON 在 Vite 的 module graph 里,改动不需要重启 dev server;`?api=` 那条 Vite 根本看不见后端。这里刻意没有断言浏览器会自动 刷新 —— App.tsx 只导出组件,是 react-refresh 的边界,更新可能被 保状态的重渲染吸收,而这一点脱离实跑无法从代码确认;写不确定的机制 断言正是本 issue 要清的那类虚构。改成「视图仍是旧文档就刷新页面」, 两种机制下都成立,且对读者可操作。 无 changeset:包 README 的文档修正,与 #3602(同一文件,同样只改 README) 先例一致;ci.yml / lint.yml 对 `**/*.md` 走 paths-ignore。 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt --- packages/runner/README.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/packages/runner/README.md b/packages/runner/README.md index 4f4ca122e8..d627e12754 100644 --- a/packages/runner/README.md +++ b/packages/runner/README.md @@ -97,9 +97,21 @@ that do configure it are: ## Development Workflow -1. Create a schema file (JSON or TypeScript) +1. Author the metadata as JSON — both loaders resolve fixed `.json` paths, and JSON is + the only shape either of them can load. Pick one of the two routes described under + [Metadata Loading](#metadata-loading): + - **Bundled** — create `packages/runner/src/app-data/` and put `app.json` plus one + `pages/.json` per route in it (route `/` is `pages/index.json`). That + directory is git-ignored, absent from a fresh checkout, and no script in this repo + creates it, so making it is a step you do by hand — until it exists, every load + returns nothing and the page renders as a 404. + - **Served** — run a backend that answers `/app.json` and + `/pages/.json`, then open the runner with `?api=`. 2. Start the runner with `pnpm dev` -3. Edit the schema - changes reload automatically +3. Edit the metadata. Under `src/app-data/` the dev server picks the change up without a + restart, because that JSON is part of Vite's module graph; behind `?api=` it cannot, + because Vite never sees your backend. Reload the page if the view still shows the + previous document. 4. Test your UI in the browser 5. Build for production with `pnpm build`