From ab0d2f3f50c0a78d49860f4a01920156bd2240fe Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 7 Aug 2026 17:14:16 +0000 Subject: [PATCH] =?UTF-8?q?docs(runner):=20=C2=A7vite.config.ts=20?= =?UTF-8?q?=E6=94=B9=E5=86=99=E4=B8=BA=E6=8C=87=E8=B7=AF=E7=9C=9F=E5=AE=9E?= =?UTF-8?q?=E6=96=87=E4=BB=B6=20+=20=E7=82=B9=E5=90=8D=E4=B8=A4=E4=B8=AA?= =?UTF-8?q?=E6=89=BF=E9=87=8D=E4=B8=8D=E5=8F=98=E9=87=8F=20(#3643)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 原展示块给出的 `server: { port: 5173, open: true }` 在 `packages/runner/vite.config.ts` 里根本不存在 —— 5173 是 Vite 的默认端口 (`"dev": "vite"`,无 `--port`/`--open`),自动开浏览器纯属无中生有。与此同时, 真实文件里唯二承重的两块被完全隐去:`resolve.alias` 传递闭包表(objectui#3575 的硬不变量,漏一个 specifier 会让 dev server 对整条 import 链返回 HTTP 500) 与 `build.modulePreload: false`(1776 个 asset / ~1761 个图标微 chunk 的防预载)。 照抄该块去替换真实文件会直接复现 #3575 的故障形态,所以这里不换一份"更准的 代码块"——按 §Where the Code Lives(#3539)的先例改为说明形态:链接到真实 文件(该 blob/main URL 受 check-doc-links 机械校验,文件挪走即红),点名两个 不许删的面及其原因,并明确写出真实文件"没有 server 块"这一否定事实。 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt --- content/docs/utilities/runner.mdx | 49 ++++++++++++++++++++++--------- 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/content/docs/utilities/runner.mdx b/content/docs/utilities/runner.mdx index db5f6168f8..79a3cf9d9c 100644 --- a/content/docs/utilities/runner.mdx +++ b/content/docs/utilities/runner.mdx @@ -160,20 +160,41 @@ load returns `null`, and `/` renders the built-in `No index page found.` placeho ### `vite.config.ts` -The Runner uses Vite for development and building: - -```typescript -import { defineConfig } from 'vite' -import react from '@vitejs/plugin-react' - -export default defineConfig({ - plugins: [react()], - server: { - port: 5173, - open: true, - }, -}) -``` +The Runner's Vite config is +[`packages/runner/vite.config.ts`](https://github.com/objectstack-ai/objectui/blob/main/packages/runner/vite.config.ts). +It is deliberately **not** reproduced on this page: the two parts of it that matter are +hard invariants, and a copy here would be the first thing to drift out of step with them. +Read the file — its own comments carry the reasoning, and a shell command that +re-derives the alias closure described below. + +What it does **not** contain is a `server` block. The `http://localhost:5173` used +throughout this page is Vite's own default port, not a configured one, and nothing tells +the dev server to open a browser — `pnpm dev` prints the URL and waits. + +The two things in that file you must not drop when you edit it: + +- **`resolve.alias` — this is why the Runner boots from a plain checkout.** The table + maps `@object-ui/*` specifiers onto each package's `src` directory, which is what lets + [From Source](#from-source) be `pnpm install` then `pnpm dev`, with no `pnpm -w build` + in between. It has to be the **transitive closure**, not just the Runner's own direct + imports: any `@object-ui/*` imported anywhere under the `src` of a package that is + already aliased needs its own entry too. A specifier that is missing falls back to Node + resolution, lands on `packages//dist` — which does not exist in an install-only + checkout — and the dev server then answers HTTP 500 for **every** module on that import + chain. That is + [#3575](https://github.com/objectstack-ai/objectui/issues/3575): `plugin-kanban` was + aliased, the `fields` and `plugin-detail` that it imports were not. +- **`build.modulePreload: false` — it keeps the icon code-split from backfiring.** The + alias table is not scoped to `serve`, so `pnpm build` bundles those packages from + source as well, and the per-icon chunks that `components/src/lib/lazy-icon.tsx` creates + stop being inlined. Measured when the table was completed (#3575), the build went from + 10 assets to 1776, about 1761 of them sub-2KB icon micro-chunks. Vite's default + `modulePreload: true` emits a preload link for every one — `index.html` measured + 546 B → 145 KB — so the browser eagerly fetches all of them on first paint and the lazy + split turns into a pessimisation. `apps/console` disables it for the same reason. + +⛔ Do not paste a Vite config out of this page, or any other guide, over that file. +Anything that arrives without the alias table reproduces #3575 exactly. ### Adding Custom Plugins