# Package 配置说明

## 当前配置：源码模式

此包目前使用**源码模式**（Source-First）配置，直接引用 TypeScript 源文件。

### 当前配置

```json
{
  "main": "src/index.ts",
  "types": "src/index.ts",
  "exports": {
    ".": {
      "import": "./src/index.ts",
      "require": "./src/index.ts",
      "types": "./src/index.ts"
    }
  },
  "files": ["src"]
}
```

### 为什么使用源码模式？

1. **Monorepo Workspace 优化** - 在 pnpm workspace 中，消费者项目可以直接引用源码，无需等待编译

2. **更好的 IDE 支持** - TypeScript 源码提供完整的类型信息和 JSDoc 注释

3. **更快的开发迭代** - 修改源码后无需重新构建即可在消费者项目中看到变化

4. **现代构建工具支持** - Vite、Webpack、esbuild 等工具可以直接处理 TypeScript

### 局限性

- 源码模式仅适用于 monorepo 内部使用
- 如果发布到 npm，需要切换到编译产物模式

## 未来发布到 npm

如果需要将此包发布到 npm，需要以下更改：

### 1. 更新 package.json

```json
{
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"]
}
```

### 2. 更新 tsconfig.json

确保 `declaration` 和 `declarationMap` 已启用：

```json
{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist"
  }
}
```

### 3. 发布前构建

```bash
# 运行构建
pnpm build

# 验证 dist 目录
ls -la dist/

# 发布到 npm
pnpm publish
```

## 编译脚本

包提供了以下编译相关脚本：

```bash
# 构建包（输出到 dist/）
pnpm build

# 开发模式（监听文件变化）
pnpm dev

# 类型检查（不生成文件）
pnpm typecheck
```

## Workspace vs NPM

| 特性 | Workspace 源码模式 | NPM 编译模式 |
|------|-------------------|-------------|
| 入口 | `src/index.ts` | `dist/index.js` |
| 发布 | 不发布 | 发布到 npm |
| 类型 | 源码 .ts 文件 | .d.ts 声明文件 |
| 用途 | Monorepo 内部 | 公共包 |
| 构建 | 可选 | 必需 |

## 迁移检查清单

如果需要从源码模式迁移到编译模式：

- [ ] 更新 `package.json` 中的 `main`, `types`, `exports`, `files`
- [ ] 确保 `tsconfig.json` 启用 `declaration` 和 `declarationMap`
- [ ] 运行 `pnpm build` 生成编译产物
- [ ] 验证 `dist/` 目录结构
- [ ] 更新 `files` 字段为 `["dist"]`
- [ ] 测试导入是否正常工作
- [ ] 更新 README.md 中的安装说明（移除 `@workspace:*`）