npm-library-setup

使用 ESM 设置 npm 库

本技能提供了使用 package.json 设置 npm 库的全面指南，并优先采用 ES Modules（ESM）。

概述

本技能可帮助你创建 npm 包，以便：

• 使用带有 "type": "module" 的 ES Modules（ESM）
• 配置现代 exports 字段（不使用已弃用的 module 字段）
• 使用 bunchee 实现零配置打包
• 使用 vitest 进行现代化测试
• 支持 TypeScript 和 React 组件库

何时使用本技能

适用于：

• “设置 npm 包”
• “创建新的 npm 库”
• “为 ESM 配置 package.json”
• “设置 TypeScript npm 包”
• “创建 React 组件库”

涵盖类别：

• 使用 ESM 进行基本包设置
• TypeScript 包配置
• React 组件库设置
• 使用 bunchee 配置构建
• 使用 vitest 配置测试

快速开始

1. 初始化包：

   npm init -y
   

2. 在 package.json 中添加 "type": "module"，以配置 ESM

3. 安装构建和测试工具：

   npm install -D bunchee vitest
   

4. 在 src/ 中创建源文件，并运行 npm run build

基本配置

package.json

{
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "bunchee",
    "test": "vitest",
    "test:run": "vitest run"
  },
  "engines": {
    "node": ">=20"
  }
}

注意： 使用目前仍受维护的最早 LTS 版本（请查看 Node.js Release Schedule）。

核心原则

1. ESM 优先：纯 ESM 包使用 "type": "module"
2. 现代 exports：使用 exports 字段，而非已弃用的 module 字段
3. 零配置打包：Bunchee 会自动处理大多数配置
4. 文件扩展名：在导入中使用明确的 .js 扩展名（TypeScript 中也一样）
5. 短横线命名文件：文件路径使用短横线命名

TypeScript 设置

安装 TypeScript 并进行配置：

npm install -D typescript @types/node

创建 tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "NodeNext",
    "declaration": true,
    "strict": true
  }
}

Bunchee 会自动编译 TypeScript 并生成 .d.ts 文件。

React 组件库

将 React 安装为开发依赖：

npm install -D react @types/react

配置 peerDependencies：

{
  "peerDependencies": {
    "react": "*"
  }
}

最佳实践

1. ✅ 使用 exports 字段（不使用已弃用的 module 字段）
2. ✅ 在导入中使用明确的文件扩展名（.js）
3. ✅ 文件路径使用短横线命名
4. ✅ 将运行时依赖与开发依赖分开
5. ✅ 使用仍受维护的最早 LTS 版本指定 Node.js 版本
6. ✅ 使用 ESM 语法编写源代码

常见模式

ESM 导入/导出

// Named exports
export function greet(name) {
  return "Hello, " + name + "!";
}

// Default export
export default class MyLibrary {}

// Import
import { greet } from './module.js';
import MyLibrary from './MyLibrary.js';

重要： 导入时始终使用 .js 扩展名，即使是在 TypeScript 文件中。

文件结构

my-package/
├── package.json
├── src/
│   ├── index.js         # or index.ts
│   └── helpers.js
├── dist/                # Build output
└── README.md

参考资料

详细指南请参见 references/ 目录：

• 入门指南
• Package.json 配置
• ESM 语法和模式
• 构建和测试
• TypeScript 包
• React 包
• 最佳实践

示例

完整的可运行示例请参见 examples/ 目录：

• JavaScript ESM 包
• TypeScript ESM 包

其他资源

• Node.js Release Schedule - 查看仍受维护的最早 LTS 版本
• Bunchee Documentation - 构建工具
• Vitest Documentation - 测试运行器