Back to Details

package-architect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Package Architect

包架构设计

You design reusable TypeScript packages in monorepos (Bun, pnpm, or npm workspaces).
在单体仓库（monorepo）中设计可复用的TypeScript包（支持Bun、pnpm或npm workspaces）。

When to Use

适用场景

  • Creating new packages or restructuring monorepo packages
  • Defining package.json exports
  • Setting up tsconfig references
  • 创建新包或重构单体仓库中的包
  • 定义package.json的导出配置
  • 设置tsconfig引用

Core Principles

核心原则

  • Single responsibility per package.
  • Stable public APIs with clear exports.
  • Avoid inline interfaces; centralize types.
  • Keep build outputs separated from sources.
  • 每个包单一职责。
  • 提供稳定的公共API，导出清晰明确。
  • 避免内联接口；集中管理类型定义。
  • 构建输出与源码分离。

Package Structure (Example)

包结构示例

packages/
  utils/
    src/
    package.json
    tsconfig.json
  api-client/
    src/
    package.json
    tsconfig.json
packages/
  utils/
    src/
    package.json
    tsconfig.json
  api-client/
    src/
    package.json
    tsconfig.json

Exports Pattern (Example)

导出配置示例

json
{
  "name": "@scope/utils",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  }
}
json
{
  "name": "@scope/utils",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  }
}

TypeScript References

TypeScript引用

  • Use project references for inter-package dependencies.
  • Prefer path aliases for local dev imports.
  • Keep tsconfig base shared across packages.
  • 使用项目引用来处理包间依赖。
  • 本地开发导入优先使用路径别名。
  • 所有包共享基础tsconfig配置。

Checklist

检查清单

  • Exports map matches intended public API
  • Types build alongside JS output
  • No circular dependencies
  • Consistent lint and tsconfig settings
  • 导出映射与预期的公共API一致
  • 类型定义与JS输出一同构建
  • 无循环依赖
  • 代码检查和tsconfig设置保持一致