如何更好地发布 TypeScript npm 包

当发布 TypeScript 编写的 npm 包时，应该遵循一些最佳实践来确保包的可用性和可维护性。以下是推荐的项目结构和发布流程：

推荐的项目结构

my-package/
├── src/                # TypeScript 源代码
│   ├── index.ts        # 主入口文件
│   └── ...             # 其他源文件
├── dist/               # 编译后的 JavaScript 文件 (由构建工具生成)
├── types/              # 类型声明文件 (通常执行tsc会自动生成)
├── test/               # 测试代码
├── package.json
├── tsconfig.json       # TypeScript 配置
└── README.md

关键步骤

1. 分离源码和编译输出

   • 保持 src/ 和 dist/ 分离
   • 将 dist/ 添加到 .gitignore

2. 配置 TypeScript 编译
   在 tsconfig.json 中设置:

   {
     "compilerOptions": {
       "outDir": "./dist",
       "rootDir": "./src",
       "declaration": true,  // 生成 .d.ts 类型声明文件
       "declarationDir": "./types",
       "module": "commonjs", // 或 "es2015" 根据目标环境
       "target": "es5"       // 根据需求调整
     },
     "exclude": ["node_modules", "dist", "test"]
   }
   

3. 配置 package.json

   {
     "name": "my-package",
     "version": "0.0.1-alpha.1",
     "main": "dist/index.js",          // CommonJS 入口
     "module": "dist/index.esm.js",    // ES Module 入口 (可选)
     "types": "types/index.d.ts",      // 类型声明入口
     "scripts": {
       "build": "tsc",
       "prepublishOnly": "npm run build"
     },
     "files": ["dist", "types"],       // 发布时包含的目录
     "devDependencies": {
       "typescript": "^5.8.3"
     }
   }
   

4. 构建和发布流程

   • 开发时在 src/ 中编写代码
   • 运行 npm run build 编译代码
   • 运行 npm publish 发布包 (会自动运行 prepublishOnly 脚本)

进阶建议

1. 支持多种模块格式:

   • 使用 Rollup 或 esbuild 生成 CommonJS 和 ES Module 两种格式
   • 在 package.json 中设置 "main" (CJS) 和 "module" (ESM)

2. 代码质量检查:

   • 添加 ESLint 和 Prettier
   • 设置单元测试

3. 版本控制:

   • 遵循语义化版本控制 (SemVer)
   • 使用 npm version 命令管理版本

4. 文档:

   • 提供清晰的 README
   • 使用 TypeDoc 生成 API 文档

通过这样的结构，你的 TypeScript 包将更易于维护，同时为使用者提供更好的开发体验。

发包

npm publish // 发布普通包
npm publish --access public // 发布域级包
npm unpublish --force