基于TypeScript开发的NPM包是否需要提供纯JS接口？

完全不需要额外编写针对TS函数的纯JS包装API facade层，这是投入产出比极低的冗余工作，既不能解决你担心的兼容问题，还会额外增加长期维护成本。

你用TypeScript编写源码，只要编译配置正确，本身就会输出原生JavaScript产物，同时生成对应的.d.ts类型声明文件：

• 纯JS用户拿到的就是无类型的原生JS代码，和你手写JS发布的包没有任何使用差异，完全感知不到底层是TS实现
• TS用户则可以自动获得完整的类型提示、类型校验能力，体验不会打折扣

额外加一层JS包装只会多一层无意义的调用栈，后续迭代API时还需要同时维护TS源码和包装层代码，极易出现两边逻辑不同步的bug，对兼容问题没有任何帮助。

你不需要预判所有用户的配置，只要在发布时做好以下几个标准化配置，就能覆盖99%的使用场景，这也是目前主流TS开源NPM包的通用做法：

• 多格式产物覆盖主流模块规范
  编译时输出三类产物，适配不同年代的构建环境和运行时：
  • CommonJS（CJS）格式：适配Node.js老版本、Webpack4及更早版本、未开启ESM支持的构建环境
  • ES Module（ESM）格式：适配现代浏览器、Vite/Rollup/Webpack5等现代构建工具，原生支持tree-shaking减小用户打包体积
  • 可选输出UMD格式：适配完全不使用构建工具、直接通过<script>标签在HTML中引入的场景，加载后直接挂载到全局变量即可调用
• 正确配置package.json的模块解析字段
  用标准化字段告诉各个环境应该加载哪份产物，避免路径解析错误：
  • main字段指向CJS产物入口
  • module字段指向ESM产物入口
  • types字段指向编译生成的总入口类型声明文件，供TS环境识别
  • 优先用exports字段明确声明不同导入场景对应的产物路径，目前所有主流Node.js版本和构建工具都优先识别该字段，能最大程度避免导入错配问题
  • 配置"sideEffects": false，告知构建工具你的包无全局副作用，支持更彻底的tree-shaking
• 编译时做好语法降级
  不要把高版本ES语法、TS专属语法留在发布产物里，编译时统一转译为ES2019及更低版本的通用语法，不要依赖用户侧的构建工具转译node_modules内的代码——绝大多数项目默认不会转译依赖包的代码，你自己提前做好语法降级，就能避免绝大多数语法兼容报错。
• 避免环境强绑定
  不要在核心逻辑里写死浏览器或Node.js专属API，如果要做跨环境支持，优先用能力检测判断运行环境支持的API，不要硬编码判断运行环境。

你不需要为极端小众的配置做提前兼容，发布前只需要做三类基础验证：Node.js下CJS方式require()引入正常、Vite等现代构建工具下ESM import引入正常、HTML直接引入UMD产物正常，就可以覆盖绝大多数用户场景。真遇到小众环境的兼容问题，等用户反馈后再针对性调整即可，过度提前兼容只会徒增包体积和维护负担。

内容的提问来源于stack exchange，提问作者Erik Hermansen