Expert guidance for building l…

# TypeScript npm 工具库发布规划（30个函数规模）

一、package.json 导出配置

基础字段

• name / version / description / license：基础元信息，license 建议用 MIT
• type: "module"：确认模块体系（见下方双格式方案）
• main / types：指向主入口，兼容老工具链（如 ./dist/index.js 和 ./dist/index.d.ts）
• exports：Node 12+ 的现代入口映射，优先级高于 main

推荐的 exports 结构

```json

{

"exports": {

".": {

"types": "./dist/index.d.ts",

"import": "./dist/index.js",

"require": "./dist/index.cjs"

},

"./package.json": "./package.json"

}

}

```

• 若函数较多，可按模块拆分入口，如 "./string": {...}、"./array": {...}，便于 tree-shaking 和按需引入
• sideEffects: false：声明无副作用，帮助打包器 tree-shaking

构建格式建议

• 同时产出 ESM + CJS（用 tsup / unbuild / rollup 一条命令搞定）
• 加上 "files": ["dist", "README.md"] 控制发包体积

辅助字段

• engines：声明支持的 Node 版本区间
• keywords：5-10 个，利于 npm 搜索
• peerDependencies：如果依赖了 React 等宿主库，放这里而不是 dependencies

二、类型声明文件

• 30 个函数建议统一从 src/index.ts 桶导出（barrel export），构建工具自动生成 index.d.ts
• tsconfig 关键项：declaration: true、declarationMap: true（支持 IDE 跳转到源码）、strict: true
• 若拆分子路径导出（如 ./string），每个入口需有对应 .d.ts，tsup/unbuild 可自动处理
• 复杂泛型工具类型（如参数约束、返回值推导）建议单独放 types.ts 并导出，提升可用性
• 用 expectType / tsd 或 vitest 类型测试验证类型导出正确性

三、README 文档结构

1. 标题 + 一句话简介 + 徽章（版本、构建状态、license、npm 下载量）

2. 安装：npm / pnpm / yarn 三种命令

3. 快速开始：一个 10 行内能跑通的完整示例（最重要）

4. API 文档：按模块分组的函数列表，每个函数包含：签名、参数表、返回值、示例。30 个函数建议用目录（TOC）+ 分类折叠

5. 特性列表：如零依赖、TS 原生、Tree-shakable、双格式

6. 贡献指南：简述开发流程，链接 CONTRIBUTING.md

7. License：一句话

四、落地清单

• [ ] tsup 配置 ESM+CJS+类型输出
• [ ] exports 字段与产物路径一致
• [ ] `npm pub