Ivan's Blog
主题

TypeScript web

TypeScript web 表示项目把 TypeScript 作为一个或多个 Web surface 的主语言，并围绕它建立 workspace scripts、typecheck、bundler、lint/format、env contract 和前端构建门禁。这里的主语不是“仓库里出现了 .ts 文件”，而是 TypeScript 已经决定了维护者怎样启动、构建、校验和交付实际 Web surface。

  • 前端

目录

Definition

TypeScript web 表示项目把 TypeScript 作为一个或多个 Web surface 的主语言，并围绕它建立 workspace scripts、typecheck、bundler、lint/format、env contract 和前端构建门禁。这里的主语不是“仓库里出现了 .ts 文件”，而是 TypeScript 已经决定了维护者怎样启动、构建、校验和交付实际 Web surface。

这个 Topic 是 Web 技术栈里的基础层，而不是 UI runtime 或组件系统本身。React app 解释单页应用 runtime，Astro site / Next.js app 解释页面交付形态，shadcn/ui 解释 open-code component layer，Storybook / Playwright 解释验证 surface；TypeScript web 负责把这些东西粘成一套可运行、可构建、可类型校验的工程骨架（projects/kaisoumail.md、projects/blog-26.md、projects/mains-aegis.md）。

When to use

当项目存在 package.json、tsconfig*.json、Vite/Astro/Next/React scripts，且这些入口直接对应产品页面、docs site、admin UI、device Web UI 或 operator console 时使用。命中条件不是“用了 TypeScript”，而是维护者修改这个系统时，必须理解 TypeScript workspace 和 scripts 才能正确完成任务。

如果改动触及 frontend build、docs-site、admin SPA、control plane、package scripts、typecheck、bundler config、Playwright/Storybook、version injection、preview port 或 UI release artifact，就应使用本 Topic。若 TypeScript 只出现在一次性脚本、代码生成辅助、测试工具或非 Web 交付面的内部工具中，则应留在更具体的 Topic 里，不要把整个项目抬成 TypeScript web（projects/mains-aegis.md、projects/style-playbook-skills.md）。

Habits / defaults

  • 保留 root workspace 与子项目脚本边界；projects/kaisoumail.md 的 root check/typecheck/test/build 聚合多个 package。
  • 端口必须可配置或经租约注入；docs-site 和 Vite 默认端口不能直接当作 owner-facing preview。
  • TypeScript web gate 至少应覆盖 typecheck/build/lint；UI 项目再叠加 Playwright/Storybook。
  • 中文优先项目文档可以保留英文技术 token，尤其是 script name、package name、workflow name。
  • 项目快照要写清 root workspace 与子 app 的职责。Bun/pnpm/npm、apps/*、web/、docs-site/、site/ 的脚本常常分别代表不同交付面，不能用一个 root build 概括全部（projects/kaisoumail.md、projects/blog-26.md）。
  • 默认把 package manager 视为 runtime contract 的一部分。Bun/pnpm/npm 不只是安装工具，它会影响 lockfile、workspace 解析、脚本行为和 CI 复现；知识库里要明确记录实际采用者，而不是只写“前端项目”（projects/kaisoumail.md、projects/blog-26.md）。
  • 对 hybrid repo，要先判断 TypeScript surface 是独立 app、docs-site、embedded UI 还是设备控制台。像 projects/blog-26.md 同时有 Astro public site、Vite admin 和 legacy Next；像 projects/loadlynx.md 则是设备仓里的 Web UI。回答问题时不能默认它们都是“单一 Web 前端”。
  • 对 owner-facing Web UI，类型通过只是最低门槛；需要根据风险补 Storybook、Playwright、visual evidence 或真实浏览器验证，尤其是表单、表格、长文本和响应式布局（projects/proxy-broker.md、projects/loadlynx.md）。
  • TypeScript Web 改动默认要核对 env 和 version 注入链。像 projects/blog-26.md 的 gateway/多 runtime 脚本、projects/codex-vibe-monitor.md 的 VITE_APP_VERSION 写入，都是“build 通过但运行结果不对”最常见的来源。

Reference implementations

  • projects/kaisoumail.md：Bun workspace + Cloudflare Worker/Web/docs-site。
  • projects/blog-26.md：Astro + Admin SPA + legacy Next TypeScript runtime。
  • projects/mains-aegis.md：Vite Web 管理台和 Rspress docs-site。
  • projects/loadlynx.md：设备 Web UI 与 firmware mono-repo 共存。
  • projects/codex-vibe-monitor.md：React dashboard 与 Rust service 一起发布，适合检查 TypeScript build 如何参与 Docker/runtime version injection。
  • projects/flux-purr.md：设备控制台把 TypeScript Web surface 放在硬件/firmware repo 中，提醒维护者不要忽略 device context。

Failure modes

  • 只看 root package 会漏掉 web/package.json 或 apps/web/package.json。
  • 把 docs-site 和 product app 混成一个 surface，会让构建/发布证据不清。
  • TypeScript build 通过不代表浏览器行为通过。
  • 忽略 lockfile/package manager 会造成本地验证与 CI 不一致；项目快照应记录 Bun/pnpm/npm 选择和关键脚本，而不是只写“TypeScript 项目”（projects/kaisoumail.md）。
  • 只按语言标签生成 Topic，会把 Astro/React/Next/shadcn/Storybook 等真实工程模式压扁；Taxonomy 应同时保留基础 Web tooling 和具体 runtime/component/QA Topic（projects/blog-26.md）。
  • 把 root dev / build 当成唯一入口，会让多 surface 仓库失去可操作性。修正方式是回到 project snapshot 的 Repository map 和 Runtime sections，明确每个 TypeScript surface 的独立命令、端口和输出（projects/kaisoumail.md、projects/blog-26.md）。
  • 把 TypeScript Web 当纯 UI Topic 使用，会漏掉 workspace、env、lockfile 和脚本契约；这类问题通常在部署或 CI 才爆，不会在单个组件 diff 里自己暴露。

Evidence index

  • projects/kaisoumail.md
  • projects/blog-26.md
  • projects/mains-aegis.md
  • projects/loadlynx.md

相关内容