mini-starter/packages/e2e-test-utils/PACKAGING.md

Package 配置说明

当前配置：源码模式

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

当前配置

{
  "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

{
  "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 已启用：

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

3. 发布前构建

# 运行构建
pnpm build

# 验证 dist 目录
ls -la dist/

# 发布到 npm
pnpm publish

编译脚本

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

# 构建包（输出到 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:*）