T Comm

Appearance

常见问题 ​

单文件导入 ​

单文件引入就是不从入口文件引入，而是从子目录引入：

diff
- import { flat } from 't-comm';
+ import { flat } from 't-comm/es/list/index';

有两种情况需要从单文件引入

  1. 前端工程。由于 t-comm 中使用了 nodejs 包，在前端项目中直接引入 t-comm 会因为这些依赖而报错
  2. 想要 tress-shaking，但是业务项目不支持，比如 Vue2.x 版本的 Uni App 等项目

es 目录和 lib 目录的区别 ​

  • es 导出的内容属于 ESM 规范
  • lib 目录导出的内容数据 CommonJS 规范

导出目录结构 ​

t-comm/
├── bin/                  # CLI 命令入口文件
│   └── cli.js            # CLI 主程序
│
├── es/                   # ESM 模块构建产物（Rollup Config 1 输出）
│   ├── list/
│   │   ├── index.mjs     # 模块入口（注意扩展名为 .mjs）
│   │   └── flat.mjs      # 具体实现
│   ├── debounce/
│   │   └── debounce.mjs
│   ├── index.mjs         # ESM 聚合入口（re-export 所有子模块）
│   ├── index.d.ts        # 类型声明（tsconfig.es.json 生成）
│   └── *.js              # Rollup 提取的公共 chunk
│
├── lib/                  # CJS 模块构建产物（Rollup Config 0 输出）
│   ├── list/
│   │   ├── index.js      # 模块入口
│   │   └── flat.js       # 具体实现
│   ├── debounce/
│   │   └── debounce.js
│   ├── index.js          # CJS 聚合入口（package.json main 字段）
│   ├── index.esm.js      # ESM 聚合入口（package.json module 字段，Rollup Config 2 输出）
│   ├── index.d.ts        # 类型声明入口（package.json typings 字段，API Extractor 合并产物）
│   └── *.js              # Rollup 提取的公共 chunk
│
└── README.md             # 项目说明文档

构建产物分析 ​

构建流程 ​

构建由 Gulp + Rollup 驱动，执行 npm run build 时依次完成：

  1. 类型检查：tsc --noEmit --skipLibCheck（package.json 的 type-check 脚本）
  2. 清理旧产物：同时删除 lib/ 和 es/ 目录（clearLibFile 任务）
  3. Rollup 打包：按三个 config 依次构建（buildByRollup 任务）
  4. 生成声明文件：API Extractor 合并 .d.ts 为 lib/index.d.ts（generateDts 任务）

Rollup 三个 Config 的分工 ​

Config输入输出格式说明
Config 0所有 src/**/*.ts（多入口）lib/CJS生成各子模块的 .js 文件，declaration: false，使用 tsconfig.json
Config 1所有 src/**/*.ts（多入口）es/ESM生成各子模块的 .mjs 文件（entryFileNames: '[name].mjs'），使用 tsconfig.es.json
Config 2src/index.ts（单入口）lib/index.esm.jsESM生成聚合入口，declaration: true 输出分散 .d.ts，使用 tsconfig.build.json

产物文件说明 ​

lib/ 目录（CJS，package.json 的 main 字段）

lib/
├── index.js          # CJS 聚合入口（package.json main 字段）
├── index.esm.js      # ESM 聚合入口（package.json module 字段）
├── index.d.ts        # 类型声明入口（package.json typings 字段，API Extractor 合并产物）
├── <module>/         # 各子模块目录，每个对应 src/ 下的一个模块
│   ├── index.js
│   └── *.js
└── *.js              # 公共 chunk（rollup 提取的共享代码）

es/ 目录（ESM，支持 Tree Shaking）

es/
├── index.mjs         # ESM 聚合入口，re-export 所有子模块
├── index.d.ts        # 类型声明（tsconfig.es.json 生成）
├── <module>/         # 各子模块目录
│   └── *.mjs
└── *.js              # 公共 chunk

es/index.mjs 的特点 ​

  • 以具名导出（named export）方式聚合所有子模块，共导出 100+ 个模块
  • 每个导出精确到具体函数，例如：
    js
    export { flat, flatten } from './list/flat.mjs';
export { debounce, debounceRun } from './debounce/debounce.mjs';
  • 末尾有部分 import 语句（无导出），用于执行副作用模块的初始化

lib/index.d.ts 的生成过程 ​

  1. Rollup Config 2（单入口）的 @rollup/plugin-typescript 先生成分散的 .d.ts
  2. API Extractor 读取 lib/index.d.ts 作为入口，将所有类型合并为单一文件
  3. 清理 lib/ 下多余的 .d.ts 文件，只保留 index.d.ts

⚠️ 注意：tsconfig.json 的 include 不能包含 test 目录，否则测试文件的类型会干扰 .d.ts 的生成，导致 lib/index.d.ts 无法正常输出。构建专用配置见 tsconfig.build.json。