web-tanstackstart 模板

web-tanstackstart 是独立单包 Web 应用模板。它保留 AgentDock 的 core / features / infra 语义边界，但不使用 monorepo 或 Turborepo。

技术栈

目录契约

src/routes/       TanStack Start 文件路由
src/components/   共享展示组件
src/core/         领域类型与仓储契约
src/features/     通过 __contract__.ts 与 index.ts 暴露的 feature
src/infra/        Drizzle schema、client、仓储实现与 provider 装配

/{locale}/hello 参考 feature 演示完整链路：

1. TanStack server function
2. feature 公开边界
3. core 仓储契约
4. 默认 SQLite 实现
5. 使用相同契约的 Supabase Postgres 实现

默认界面面向 App 右侧面板：Web 嵌入其中，充当 App 内 AI agent 的辅助工作台（默认约 380px，硬下限 360px）。壳层是容器查询（container query）驱动、底部导航、无顶部栏，因此没有页面会再花一行重复壳层：

• 一级路由是落地页（index）：视觉隐藏的 h1、一行说明，以及指向下一级路由的模块入口；
• 二级页使用整屏 PageShell 骨架：页面自身不滚动，只有内容区滚动（不再包裹卡片框），返回入口永远不会被滚走；
• 配置与表单进右侧 SideDrawer（不铺蒙版、点外部不关闭），罕见操作收进一个 end 对齐的 MoreMenu；
• 卡片是例外：页面由分区与行构成，卡片外框永不嵌套。

共享布局原语位于 src/components/layout：TemplateShell、BottomNav、PageContainer、PageTopBar、PageShell、SideDrawer、HorizontalFields。Shell 默认包含：

• Astryx 预编译 Neutral、Butter、Matcha、Stone 主题；
• 跟随系统、浅色、深色三种颜色模式；
• 简体中文（/zh-CN，默认）与英文（/en）URL 前缀路由；
• /{locale}/settings 路由（Settings Surface：分区导航 + 单一滚动面板）承载外观与语言控件，外观偏好用第一方 Cookie 持久化，切换语言保留当前页面。

Agent 开发指南

生成项目内置根目录 LLM.md，集中说明技术选型理由、依赖边界、feature 开发流程、数据库变更、UI 开发、验证方式和故障排查。AGENTS.md 继续作为执行边界契约，并优先指向 LLM.md。

数据源

默认 SQLite 不需要外部服务：

DATA_PROVIDER=sqlite
SQLITE_DATABASE_URL=./data/app.db

切换到 Supabase Postgres：

DATA_PROVIDER=supabase
SUPABASE_DATABASE_URL=postgres://YOUR_USER:YOUR_PASSWORD@YOUR_HOST:6543/postgres

Postgres client 使用 prepare: false，兼容 Supabase transaction pooler。首版面向企业内网中长期运行的 Node 服务，不提供无状态平台下的 SQLite 持久化方案。

项目支持 pnpm >=10.34.5 <13，推荐 12.4.1。模板不写精确 packageManager pin，因此受支持的 pnpm 10/11/12 不会触发自动切换；engineStrict 会阻止范围外版本。低于 10.34.5 时可在同一 major 内更新到 10.34.5，或使用推荐的 npx pnpm@12.4.1。

UI

Astryx 提供组件、预编译主题、语言目录和 CSS。模板遵循 Astryx-first 组合原则：优先使用原生布局、集合、反馈和内容组件，再考虑增加薄封装；其余业务样式通过官方 Astryx Vite StyleX 插件实现。主题与语言扩展规则见 LLM.md 和 DESIGN.md。

使用方式见 模板使用。项目确定自身视觉方向后，应同步更新 DESIGN.md。