From 7281a4f2e613797fa500eb01650363c12b44ce84 Mon Sep 17 00:00:00 2001
From: yeuimu <2197651308@qq.com>
Date: Tue, 18 Aug 2026 09:06:24 +0000
Subject: [PATCH] docs: workspace packages must be rebuilt before the backend
 (silent stale-dist trap)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The backend never compiles @teable/* sources — it loads packages/*/dist via
node_modules symlinks (@teable/v2-core is a webpack external, read at runtime
from packages/v2/core/dist/index.cjs). Editing a package's src and only
rebuilding apps/nestjs-backend ships nothing: no error, old behavior online.
Documented the correct build order + verification greps in AGENTS.md and the
skill's development guide (found while shipping the defaultValue cascade fix).
---
 .../inkreach-teable/guides/development.md     | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/.agents/skills/inkreach-teable/guides/development.md b/.agents/skills/inkreach-teable/guides/development.md
index e161e15..78bde34 100644
--- a/.agents/skills/inkreach-teable/guides/development.md
+++ b/.agents/skills/inkreach-teable/guides/development.md
@@ -53,6 +53,28 @@ untouched (node_modules paths are treated as immutable cache inputs). Symptom: b
 behavior unchanged after a code change. Fix: `rm apps/nestjs-backend/dist/index.js`
 then rebuild, and verify with `grep '<your-new-string>' dist/index.js`.
 
+### Workspace packages must be rebuilt BEFORE the backend (else stale dist ships)
+Distinct from the cache trap above: `apps/nestjs-backend` never compiles `@teable/*`
+sources — it resolves `@teable/core`, `@teable/v2-core`, `@teable/openapi` … via
+`node_modules` symlinks to `packages/*/dist`. `@teable/v2-core` in particular is a
+webpack EXTERNAL: the running backend reads `packages/v2/core/dist/index.cjs` directly
+at runtime, so a backend rebuild does not even copy it.
+
+SILENT FAILURE MODE (hit 2026-08-18, select-defaultValue cascade fix): edit
+`packages/core/src/…` + `packages/v2/core/src/…` → only rebuild backend + restart →
+live API keeps the old behavior, no error anywhere. Correct order:
+
+```bash
+pnpm --filter @teable/core build     # tsc → packages/core/dist/**
+pnpm --filter @teable/v2-core build  # tsdown → dist/index.cjs + dist/index.js
+cd apps/nestjs-backend && rm -f dist/index.js && pnpm build   # bundle + externals
+# verify the new code actually shipped BEFORE restarting:
+grep '<new-string>' packages/core/dist/<path>.js
+grep '<new-string>' packages/v2/core/dist/index.cjs
+# then the best-path restart (:3003)
+```
+(Many packages at once: `pnpm -F './packages/**' build`, then backend build.)
+
 ### Node v24 fetch drops the Authorization header
 The global `fetch()` on Node v24 (undici) drops the `Authorization` request
 header in certain cases (redirects, proxies). **Use `node:http`/`node:https`**