From a69f6d853833841f18c41884fba785af51c204a5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Aug 2026 19:46:42 +0000
Subject: [PATCH] =?UTF-8?q?docs(runner):=20=E6=8C=89=E5=AE=9E=E6=B5=8B?=
 =?UTF-8?q?=E9=97=AD=E5=90=88=20=C2=A7Features=20=E6=8F=92=E4=BB=B6?=
 =?UTF-8?q?=E6=96=AD=E8=A8=80,=E4=B8=89=E5=A4=84=20main.tsx=20=E8=AE=A2?=
 =?UTF-8?q?=E6=AD=A3=E4=B8=BA=20App.tsx=20(#3619)=20(#3652)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#3619:§Features 的「All official plugins included」与同页 §Pre-installed Plugins
自相矛盾 —— runner 的 dependencies 里只有 plugin-kanban 与 plugin-charts 两个
plugin-*,而仓库里有 19 个 packages/plugin-*。措辞与 PR #3644 在 README 侧落地的
口径对齐,不留开放集合暗示。

#3652:三处把 src/main.tsx 指认为插件 import 所在地(§Adding Custom Plugins 第 2 步、
§Use Cases 代码注释、§Troubleshooting 排查步骤),但真实 main.tsx 共 18 行、零个
@object-ui/plugin-* import;side-effect import 在 App.tsx:13-15。Troubleshooting
那处危害最大 —— 排查步骤指向一个永远看不到 import 的文件,既不能证实也不能证伪,
线索到此断掉;改写为可执行的排查动作,并点明 main.tsx 看不到的原因。

§Adding Custom Plugins 的 npm link 建议按 pnpm workspace 实况改写:仅换掉 npm link
仍会留下一份跑不通的步骤 —— 缺 vite.config.ts 别名条目即复现 #3575 的 HTTP 500。
补齐两个预装插件实际具备的四个接线点(package.json 的 workspace:* 依赖、App.tsx
注册 import、vite.config.ts 别名、index.css 的 @source),与 README(#3644)一致。

无 changeset:站点文档单文件改动,同页前三次改动(#3633/#3646/#3651)均无。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
---
 content/docs/utilities/runner.mdx | 60 ++++++++++++++++++++++++-------
 1 file changed, 47 insertions(+), 13 deletions(-)

diff --git a/content/docs/utilities/runner.mdx b/content/docs/utilities/runner.mdx
index 79a3cf9d9c..e2c8ff8a24 100644
--- a/content/docs/utilities/runner.mdx
+++ b/content/docs/utilities/runner.mdx
@@ -17,7 +17,7 @@ The Runner is a complete ObjectUI application that demonstrates best practices a
 - 🧪 **Plugin Testing** - Test plugins in isolation
 - 🎨 **Example Implementations** - Reference code
 - 🚀 **Development Playground** - Experiment with schemas
-- 📦 **Pre-configured** - All official plugins included
+- 📦 **Pre-configured** - The Kanban and Charts plugins, wired up out of the box
 
 ## Running the Runner
 
@@ -198,25 +198,48 @@ Anything that arrives without the alias table reproduces #3575 exactly.
 
 ### Adding Custom Plugins
 
-To test your own plugin:
+There is no runtime plugin installation — a plugin reaches the Runner only by editing the
+Runner's own sources. Steps 1-4 below are the four wiring points `plugin-kanban` and
+`plugin-charts` already have, so those two are a working reference for each of them.
 
-1. **Link your plugin:**
+Your plugin needs a place in this pnpm workspace first. `pnpm-workspace.yaml` globs
+`packages/*`, so a package created at `packages/plugin-yourplugin` is picked up by
+`pnpm install` from the repo root. (`npm link` is not the tool here — this repo is a
+strict pnpm workspace.)
 
-```bash
-# In your plugin directory
-npm link
+1. **Depend on it** in `packages/runner/package.json`, through the workspace protocol,
+   then re-run `pnpm install` from the repo root:
 
-# In runner directory
-npm link @object-ui/plugin-yourplugin
+```json
+"dependencies": {
+  "@object-ui/plugin-yourplugin": "workspace:*"
+}
 ```
 
-2. **Import in `src/main.tsx`:**
+2. **Register it** with a side-effect import in `src/App.tsx`, alongside the two
+   pre-installed plugins:
 
 ```typescript
 import '@object-ui/plugin-yourplugin'
 ```
 
-3. **Use in schemas:**
+3. **Alias it** in `packages/runner/vite.config.ts` — together with every `@object-ui/*`
+   package your plugin's own `src` imports, since that table has to stay the transitive
+   closure. Skipping this is what the `vite.config.ts` section above describes: the dev
+   server answers HTTP 500 for every module on the import chain.
+
+```typescript
+"@object-ui/plugin-yourplugin": path.resolve(__dirname, "../../packages/plugin-yourplugin/src"),
+```
+
+4. **Add a Tailwind `@source`** line in `src/index.css`, so the classes your plugin's
+   components use survive the CSS build:
+
+```css
+@source '../../packages/plugin-yourplugin/src/**/*.{ts,tsx}';
+```
+
+5. **Use in schemas:**
 
 ```json
 {
@@ -234,7 +257,7 @@ import '@object-ui/plugin-yourplugin'
 Test new plugins in a full application context:
 
 ```typescript
-// src/main.tsx
+// src/App.tsx
 import '@object-ui/plugin-myplugin'
 
 // src/app-data/pages/index.json — the page served at "/"
@@ -533,12 +556,23 @@ export default defineConfig({
 
 ### Plugin Not Loading
 
-Check if plugin is imported in `main.tsx`:
+A plugin registers itself through the side-effect imports in `src/App.tsx`. `main.tsx`
+only mounts the root component and imports no plugin at all — not even the two
+pre-installed ones — so looking there can neither confirm nor rule anything out. Open
+`src/App.tsx` and check yours sits with the two known-good imports:
 
 ```typescript
-import '@object-ui/plugin-yourplugin'
+import '@object-ui/plugin-kanban';
+import '@object-ui/plugin-charts';
+import '@object-ui/plugin-yourplugin';  // yours belongs here
 ```
 
+If the import is there and the page still shows an **Unknown component type** box, the
+`type` in your schema and the key the plugin registers do not match — compare the two.
+If instead the dev server returns HTTP 500 for the plugin's modules, its `vite.config.ts`
+alias entry is missing; see [Adding Custom Plugins](#adding-custom-plugins) for the full
+set of wiring points a plugin needs.
+
 ### Build Errors
 
 Clear cache and rebuild: