bcrypt.js构建流程：从ESM到UMD的完整转换指南 🚀

bcrypt.js是一个零依赖的纯JavaScript实现的优化bcrypt库，支持TypeScript，与原生bcrypt兼容。本文将详细解析其从ESM模块到UMD格式的构建流程，帮助开发者深入理解现代JavaScript库的打包机制。

📦 核心依赖与项目配置

bcrypt.js的构建流程依赖于简洁而高效的工具链，主要配置文件为package.json，其中定义了构建命令和关键依赖：

• 构建命令：通过npm run build触发，实际执行scripts/build.js
• 核心构建工具：esm2umd负责模块格式转换，prettier用于代码格式化
• 入口与输出：以index.js为ESM源文件，输出到umd/index.js

// package.json 关键配置
{
  "type": "module",
  "main": "umd/index.js",
  "scripts": {
    "build": "node scripts/build.js"
  },
  "devDependencies": {
    "esm2umd": "^0.3.1",
    "prettier": "^3.5.0"
  }
}

🔄 构建流程全解析

1️⃣ 构建脚本入口：scripts/build.js

构建流程的起点是scripts/build.js，这个ES模块文件负责协调整个转换过程：

// 关键路径定义
const basePath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
const esmPath = path.join(basePath, "index.js");
const umdPath = path.join(basePath, "umd", "index.js");

2️⃣ ESM到UMD的转换核心

转换过程使用esm2umd工具将ESM模块转换为UMD格式，使其能在浏览器和Node.js环境中通用：

// 读取ESM源文件
const esmSource = fs.readFileSync(esmPath, "utf8");

// 转换为UMD格式，指定全局变量名称为"bcrypt"
const umdSource = esm2umd("bcrypt", esmSource);

3️⃣ 代码格式化与优化

转换后的代码会使用Prettier进行格式化，确保输出代码的可读性和一致性：

async function formatWithPrettier(source, filepath) {
  const options = await prettier.resolveConfig(filepath);
  return await prettier.format(source, { ...options, filepath });
}

// 应用格式化
const prettierUmdSource = await formatWithPrettier(umdSource, umdPath);

4️⃣ 类型定义文件处理

构建脚本还会处理TypeScript类型定义文件，确保UMD包也能提供完整的类型支持：

// 复制类型定义文件到UMD目录
fs.copyFileSync(
  path.join(basePath, "types.d.ts"),
  path.join(basePath, "umd", "types.d.ts")
);

📂 构建产物分析

构建完成后，UMD格式的文件会输出到umd/目录，包含以下关键文件：

• umd/index.js：转换后的UMD格式主文件，支持多种加载方式

  • 浏览器全局变量：window.bcrypt
  • CommonJS模块：require('bcryptjs')
  • AMD模块：define(['bcryptjs'], ...)

• 类型定义文件：

  • umd/index.d.ts
  • umd/types.d.ts

• 包描述文件：umd/package.json，定义UMD包的元数据

💡 构建流程优化点

bcrypt.js的构建流程体现了现代JavaScript库的最佳实践：

1. 零外部依赖：构建过程虽然依赖esm2umd和prettier，但最终产物不包含任何依赖
2. 环境适配：通过条件导出和浏览器字段(package.json#L67-L69)实现多环境兼容
3. 类型优先：全程保持TypeScript类型定义同步，提升开发体验
4. 简洁高效：构建脚本仅80行左右，却完成了从读取、转换到格式化的完整流程

🚀 快速上手：本地构建步骤

要在本地体验bcrypt.js的构建流程，只需执行以下步骤：

1. 克隆仓库：git clone https://gitcode.com/gh_mirrors/bc/bcrypt.js
2. 安装依赖：npm install
3. 执行构建：npm run build
4. 查看产物：检查umd/目录下的生成文件

通过这个构建流程，bcrypt.js实现了从现代ESM模块到通用UMD格式的无缝转换，兼顾了开发效率和生产环境的兼容性需求。这种轻量级、可复用的构建模式值得在类似的JavaScript库开发中借鉴。