sdk-development
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSDK Development
SDK 开发
Create professional TypeScript SDKs from scratch or by extraction.
从零开始或通过提取方式创建专业的TypeScript SDK。
Key Principles
核心原则
- Clean public API — Export only what consumers need, hide internals
- Type everything — Full type coverage for config, methods, responses, and errors
- Meaningful errors — Typed error classes with codes and context
- Sensible defaults — Works out of the box with minimal config
- Framework agnostic — Core SDK has no framework dependencies; add bindings separately
- 简洁的公开API — 仅导出消费者所需内容，隐藏内部实现
- 全面类型化 — 对配置、方法、响应和错误提供完整类型覆盖
- 有意义的错误 — 包含错误码和上下文的类型化错误类
- 合理的默认配置 — 只需极少配置即可开箱即用
- 框架无关 — 核心SDK无框架依赖；可单独添加绑定
Quick Start Checklist
快速开始清单
- Analyze scope: new SDK or extraction from existing app
- Design public API surface (exports, types, config)
- Implement client with typed methods and error handling
- Configure build for ESM/CJS/types (tsup recommended)
- Write tests (unit + integration) and examples
- Publish to npm with proper package.json exports field
- 分析范围：新建SDK还是从现有应用中提取
- 设计公开API接口（导出内容、类型、配置）
- 实现带有类型化方法和错误处理的客户端
- 配置构建以支持ESM/CJS/类型（推荐使用tsup）
- 编写测试（单元测试+集成测试）和示例
- 使用正确的package.json exports字段发布至npm
When NOT to Use
不适用于以下场景
- For consuming external APIs — see api-integration skill
- For publishing to npm only — this skill covers full SDK lifecycle
- 调用外部API — 请查看api-integration技能
- 仅用于发布至npm — 本技能涵盖完整的SDK生命周期
References
参考资料
| Reference | Description |
|---|---|
| extraction-scope-and-boundaries.md | Scope identification, dependency analysis, boundary definition |
| extraction-usages-and-planning.md | Finding usages, test coverage, phased extraction plan |
| package-structure-and-clients.md | SDK layout, client design patterns (single, modular, factory) |
| configuration-and-api-design.md | Config interfaces, defaults, barrel exports, method signatures |
| internal-architecture-and-best-practices.md | HTTP client, state management, tree-shaking, environment agnostic |
| type-design.md | Strict types, branded types, generics, discriminated unions |
| error-handling-and-async.md | Error class hierarchy, retry logic, request queues, token management |
| events-storage-and-logging.md | Event emitter, storage abstraction, logger interface |
| build-tools-and-output.md | tsup config, output formats, package.json exports, TypeScript config |
| bundle-optimization-and-distribution.md | Bundle size, multi-platform builds, dual packages, monorepo |
| publishing-and-registries.md | npm publishing, private registries, versioning, changelogs |
| ci-cd-and-documentation.md | GitHub Actions, documentation, pre-publish checklist, deprecation |
| 参考链接 | 描述 |
|---|---|
| extraction-scope-and-boundaries.md | 范围识别、依赖分析、边界定义 |
| extraction-usages-and-planning.md | 查找使用场景、测试覆盖度、分阶段提取计划 |
| package-structure-and-clients.md | SDK布局、客户端设计模式（单一、模块化、工厂模式） |
| configuration-and-api-design.md | 配置接口、默认值、桶导出、方法签名 |
| internal-architecture-and-best-practices.md | HTTP客户端、状态管理、摇树优化、环境无关性 |
| type-design.md | 严格类型、品牌类型、泛型、区分联合类型 |
| error-handling-and-async.md | 错误类层级、重试逻辑、请求队列、令牌管理 |
| events-storage-and-logging.md | 事件发射器、存储抽象、日志接口 |
| build-tools-and-output.md | tsup配置、输出格式、package.json exports、TypeScript配置 |
| bundle-optimization-and-distribution.md | 包大小优化、多平台构建、双包模式、单仓库 |
| publishing-and-registries.md | npm发布、私有仓库、版本管理、变更日志 |
| ci-cd-and-documentation.md | GitHub Actions、文档编写、发布前检查清单、废弃策略 |