如何为esbuild打包的JS库添加类型定义及适配全场景发布

一、生成TypeScript类型定义 #

esbuild本身不支持生成TypeScript类型定义文件（.d.ts），需要配合TypeScript编译器（tsc）单独生成，步骤如下：

1. 配置tsconfig.json
   在你的tsconfig.json中开启类型声明生成，指定输出目录，并设置仅生成类型（不编译JS，因为esbuild已完成JS编译）：

   {
     "compilerOptions": {
       "declaration": true,
       "declarationDir": "./dist/types",
       "emitDeclarationOnly": true,
       "rootDir": "./src",
       "strict": true,
       "target": "ESNext"
     },
     "include": ["src/**/*"]
   }
   

2. 更新构建脚本
   在package.json的scripts中添加先执行esbuild编译JS、再执行tsc生成类型的命令：

   {
     "scripts": {
       "build": "esbuild src/index.ts --bundle --minify --outfile=dist/index.js && tsc"
     }
   }
   

   后续若要生成多格式JS文件，可直接扩展esbuild命令，类型生成步骤保持不变。

3. 指定类型入口
   在package.json中添加types字段，让npm用户的TypeScript环境自动识别类型定义：

   {
     "types": "dist/types/index.d.ts"
   }
   

二、发布多风格JS版本以兼容所有用户 #

如果希望库能覆盖所有使用场景（Node.js、现代/旧版浏览器等），建议发布多种格式的JS版本，具体方案如下：

1. 用esbuild生成多格式文件 #

修改build脚本，让esbuild同时输出不同模块格式和目标版本的文件：

{
  "scripts": {
    "build": "esbuild src/index.ts --bundle --minify --format=esm --outfile=dist/index.esm.js && esbuild src/index.ts --bundle --minify --format=cjs --outfile=dist/index.cjs.js && esbuild src/index.ts --bundle --minify --format=umd --global-name=MyLibrary --target=es5 --outfile=dist/index.umd.es5.js && tsc --emitDeclarationOnly --outDir dist/types"
  }
}

• --format=esm：生成ES模块文件，供现代浏览器和Node.js 12+使用
• --format=cjs：生成CommonJS文件，供传统Node.js环境使用
• --format=umd：生成UMD格式文件，兼容浏览器全局变量、AMD、CommonJS环境，搭配--target=es5兼容旧浏览器

2. 配置package.json入口字段 #

通过package.json的字段让不同环境自动匹配对应文件：

{
  "main": "dist/index.cjs.js", // Node.js require()默认入口
  "module": "dist/index.esm.js", // ES模块导入入口（webpack、rollup等工具优先读取）
  "browser": "dist/index.umd.es5.js", // 浏览器环境入口
  "types": "dist/types/index.d.ts", // 类型定义入口
  "exports": { // 条件导出，精准匹配不同环境（推荐）
    ".": {
      "import": "./dist/index.esm.js",
      "require": "./dist/index.cjs.js",
      "browser": "./dist/index.umd.es5.js",
      "types": "./dist/types/index.d.ts"
    }
  }
}

3. 额外注意事项 #

• 在.gitignore中排除dist目录，避免提交构建产物，发布时通过npm publish自动上传dist内容
• 可在package.json中添加files字段，明确指定要发布的文件：

  {
    "files": ["dist", "README.md", "LICENSE"]
  }
  

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