包开发规范

packages 目录的边界、结构模板和工作区开发约定

包边界判断

先判断代码该放哪里：

• packages/：被多个 app 复用，或者本身就是清晰的领域能力
• packages/ui-shared：跨项目复用的业务组件
• apps/*/src/lib/：仅属于单个应用的业务逻辑
• apps/*/src/components/：仅属于单个应用的组件

判断标准：

• 多个 app 会用到吗
• 是否有明确 API 边界
• 能否独立测试
• 是否存在独立依赖

推荐目录结构

所有 package 统一使用 src/ 结构，并通过 src/index.ts 导出：

packages/
└── example/
    ├── package.json
    ├── tsconfig.json
    └── src/
        ├── index.ts
        └── ...

package.json 标准模板

{
  "name": "@mono/example",
  "version": "0.0.0",
  "private": true,
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": "./src/index.ts"
  },
  "scripts": {
    "type-check": "tsc --noEmit"
  },
  "dependencies": {},
  "devDependencies": {
    "typescript": "5.9.3"
  }
}

关键约定：

• main / types 使用 ./src/index.ts
• 默认只导出根入口
• 每个包都提供 type-check 脚本
• 内部依赖统一使用 workspace:*

exports 约定

简单包

{
  "exports": {
    ".": "./src/index.ts"
  }
}

复杂包

只有确实需要暴露子路径时，才开放通配导出：

{
  "exports": {
    ".": "./src/index.ts",
    "./*": "./src/*"
  }
}

通常只有这类包才需要子路径：

• @mono/auth
• @mono/ui
• @mono/utils

内部依赖规则

workspace 包之间统一使用：

{
  "dependencies": {
    "@mono/utils": "workspace:*"
  }
}

不要：

• 用相对路径跨包引用源码
• 在 app 层直接绕过包入口读 package 内部文件
• 把所有依赖堆到根 package.json 里

UI 三层架构

packages/ui

• 只放纯 shadcn/ui 原子组件
• 不手工改 packages/ui/src/components/*
• 升级方式只能是 pnpm dlx shadcn@latest add <component>

packages/ui-shared

• 放 2 个及以上 app 共享的业务组件
• 可以引入 @mono/ui
• 允许包含业务逻辑和样式封装

apps/*/src/components

• 只放单 app 使用的组件
• 不要为了复用幻想过早抽到 package

Package 和 App 的职责分界

适合放进 package

• 认证封装
• 存储客户端
• 缓存能力
• 通用 schema / validator
• 共享 UI primitives 或共享业务组件

不适合放进 package

• mono-web 专用的查询拼装
• 某个页面的表单状态逻辑
• 与单一 app 路由耦合的 server action
• 只服务一个页面的组件

开发工作流

1. 新建 package 目录和 package.json
2. 用 src/index.ts 作为统一导出入口
3. 补齐 type-check 脚本和内部依赖
4. 更新对应 README 和 Fumadocs 文档
5. 运行工作区校验

常用命令：

pnpm type-check:packages
pnpm test:packages
pnpm verify:packages

文档维护规则

• README.md：包的技术参考、API、配置、实现说明
• Fumadocs：面向模板使用者的教程和最佳实践

如果一个包被新增、拆分或修改使用方式，至少同步更新：

1. packages/<name>/README.md
2. apps/mono-web/content/docs/packages/*.zh.mdx
3. 本页中与包结构相关的约束（如有变化）

提交前检查

• 入口文件为 src/index.ts
• package.json 使用 ./src/index.ts
• 内部依赖使用 workspace:*
• 存在 type-check 脚本
• README 和文档已同步
• 没有把 app 私有逻辑错误抽进 package