#优质博文 #前端 #工程化 #esm #typescript
Tutorial: publishing ESM-based npm packages with TypeScript
AI 摘要：过去两年，TypeScript、Node.js 和浏览器对 ESM（ECMAScript Modules）的支持取得了显著进展。本教程介绍了一种较为现代、简化的 TypeScript npm 包发布方案，适用于无需考虑向后兼容性的项目。
主要内容：
1. 项目结构：包含 src/ （源码）、test/ （测试）、dist/ （编译输出）、docs/ （文档）等目录。
2. tsconfig.json 配置：
• outDir: "dist" ：编译后的文件存放在 dist/ 目录。
• sourceMap: true、declaration: true、declarationMap: true，确保源码映射和类型定义文件生成。
• verbatimModuleSyntax: true 及 erasableSyntaxOnly: true，提高 TypeScript 代码的可移植性。
3. package.json 相关配置：
•
• "exports"：明确定义包的 ESM 入口，支持子路径导出。
• "files"：严格控制发布到 npm 的文件，避免上传测试代码。
4. 构建与发布：
• 使用 npm run build 清理 dist/ 目录并重新编译。
• prepublishOnly 钩子在 npm publish 之前自动执行 build，确保发布的代码是最新的。
• publishd 命令用于 npm publish --dry-run，可预览上传的文件。
5. 测试与文档：
• 采用 Mocha 进行单元测试，并支持 source-maps 以优化错误追踪。
• 使用 TypeDoc 生成 API 文档，托管于 GitHub Pages。
6. 其他工具：
• publint、arethetypeswrong 等工具检查 npm 包的兼容性和 TypeScript 类型定义的正确性。
• shx 统一跨平台 shell 命令（如 rm -rf、chmod u+x）。
本指南基于 @rauschma/helpers 包的实践经验，提供了一种现代化、易于维护的 ESM npm 包构建方法。
via 2ality – JavaScript and more
Tutorial: publishing ESM-based npm packages with TypeScript
AI 摘要：过去两年，TypeScript、Node.js 和浏览器对 ESM（ECMAScript Modules）的支持取得了显著进展。本教程介绍了一种较为现代、简化的 TypeScript npm 包发布方案，适用于无需考虑向后兼容性的项目。
主要内容：
1. 项目结构：包含 src/ （源码）、test/ （测试）、dist/ （编译输出）、docs/ （文档）等目录。
2. tsconfig.json 配置：
• outDir: "dist" ：编译后的文件存放在 dist/ 目录。
• sourceMap: true、declaration: true、declarationMap: true，确保源码映射和类型定义文件生成。
• verbatimModuleSyntax: true 及 erasableSyntaxOnly: true，提高 TypeScript 代码的可移植性。
3. package.json 相关配置：
•
"type": "module" ：确保 .js 文件按 ESM 解析。• "exports"：明确定义包的 ESM 入口，支持子路径导出。
• "files"：严格控制发布到 npm 的文件，避免上传测试代码。
4. 构建与发布：
• 使用 npm run build 清理 dist/ 目录并重新编译。
• prepublishOnly 钩子在 npm publish 之前自动执行 build，确保发布的代码是最新的。
• publishd 命令用于 npm publish --dry-run，可预览上传的文件。
5. 测试与文档：
• 采用 Mocha 进行单元测试，并支持 source-maps 以优化错误追踪。
• 使用 TypeDoc 生成 API 文档，托管于 GitHub Pages。
6. 其他工具：
• publint、arethetypeswrong 等工具检查 npm 包的兼容性和 TypeScript 类型定义的正确性。
• shx 统一跨平台 shell 命令（如 rm -rf、chmod u+x）。
本指南基于 @rauschma/helpers 包的实践经验，提供了一种现代化、易于维护的 ESM npm 包构建方法。
via 2ality – JavaScript and more
