npm-library-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

npm Library Setup with ESM

基于ESM的npm库搭建

This skill provides comprehensive guidance on setting up an npm library with

package.json

, with a preference for ES Modules (ESM).

本指南提供了使用

package.json

搭建npm库的全面指导，优先采用ES Modules（ESM）。

Overview

概述

This skill helps you create npm packages that:

Use ES Modules (ESM) with
```
"type": "module"
```
Configure modern
```
exports
```
field (no deprecated
```
module
```
field)
Use bunchee for zero-config bundling
Use vitest for modern testing
Support TypeScript and React component libraries

本指南帮助你创建具备以下特性的npm包：

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

When to Use This Skill

使用场景

Use when:

"Set up an npm package"
"Create a new npm library"
"Configure package.json for ESM"
"Set up a TypeScript npm package"
"Create a React component library"

Categories covered:

Basic package setup with ESM
TypeScript package configuration
React component library setup
Build configuration with bunchee
Testing setup with vitest

适用场景：

"搭建npm包"
"创建新的npm库"
"为ESM配置package.json"
"搭建TypeScript npm包"
"创建React组件库"

涵盖类别：

基于ESM的基础包搭建
TypeScript包配置
React组件库搭建
使用bunchee的构建配置
使用vitest的测试配置

Quick Start

快速开始

Initialize your package:
bash
```
npm init -y
```
Configure for ESM by adding
```
"type": "module"
```
to
```
package.json
```
Install build and test tools:
bash
```
npm install -D bunchee vitest
```
Create your source files in
```
src/
```
and run
```
npm run build
```

初始化你的包：
bash
```
npm init -y
```
在
```
package.json
```
中添加
```
"type": "module"
```
以配置ESM
安装构建和测试工具：
bash
```
npm install -D bunchee vitest
```
在
```
src/
```
目录下创建源文件，然后运行
```
npm run build
```

Essential Configuration

核心配置

package.json

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"
  }
}

Note: Use the oldest currently-maintained LTS version (check Node.js Release Schedule).

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）。

Key Principles

核心原则

ESM-first: Use
```
"type": "module"
```
for pure ESM packages
Modern exports: Use
```
exports
```
field instead of deprecated
```
module
```
field
Zero-config bundling: Bunchee handles most configuration automatically
File extensions: Use explicit
```
.js
```
extensions in imports (even in TypeScript)
Kebab-case files: Use kebab-case for file paths

ESM优先：为纯ESM包使用
```
"type": "module"
```
现代exports：使用
```
exports
```
字段替代已弃用的
```
module
```
字段
零配置打包：Bunchee自动处理大多数配置
文件扩展名：在导入时使用明确的
```
.js
```
扩展名（即使在TypeScript中）
短横线命名文件：文件路径使用短横线命名法（kebab-case）

TypeScript Setup

TypeScript配置

Install TypeScript and configure:

bash

npm install -D typescript @types/node

Create

tsconfig.json

json

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

Bunchee automatically compiles TypeScript and generates

.d.ts

files.

安装TypeScript并进行配置：

bash

npm install -D typescript @types/node

创建

tsconfig.json

：

json

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

Bunchee会自动编译TypeScript并生成

.d.ts

文件。

React Component Libraries

React组件库

Install React as dev dependency:

bash

npm install -D react @types/react

Configure

peerDependencies

json

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

安装React作为开发依赖：

bash

npm install -D react @types/react

配置

peerDependencies

：

json

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

Best Practices

最佳实践

✅ Use
```
exports
```
field (no deprecated
```
module
```
field)
✅ Use explicit file extensions in imports (
```
.js
```
)
✅ Use kebab-case for file paths
✅ Separate runtime dependencies from dev dependencies
✅ Specify Node.js version using oldest maintained LTS
✅ Write source in ESM syntax

✅ 使用
```
exports
```
字段（不使用已弃用的
```
module
```
字段）
✅ 在导入时使用明确的文件扩展名（
```
.js
```
）
✅ 文件路径使用短横线命名法
✅ 区分运行时依赖和开发依赖
✅ 使用仍在维护的最旧LTS版本指定Node.js版本
✅ 使用ESM语法编写源代码

Common Patterns

常见模式

ESM Import/Export

ESM导入/导出

javascript

// 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';

Important: Always use

.js

extension in imports, even in TypeScript files.

javascript

// 命名导出
export function greet(name) {
  return "Hello, " + name + "!";
}

// 默认导出
export default class MyLibrary {}

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

重要提示： 即使在TypeScript文件中，导入时也始终要使用

.js

扩展名。

File Structure

文件结构

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

my-package/
├── package.json
├── src/
│   ├── index.js         # 或index.ts
│   └── helpers.js
├── dist/                # 构建输出目录
└── README.md

References

参考资料

See

references/

directory for detailed guides:

Getting Started
Package.json Configuration
ESM Syntax and Patterns
Building and Testing
TypeScript Packages
React Packages
Best Practices

查看

references/

目录获取详细指南：

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

Examples

示例

See

examples/

directory for complete working examples:

JavaScript ESM package
TypeScript ESM package

查看

examples/

目录获取完整的可运行示例：

JavaScript ESM包
TypeScript ESM包

Additional Resources

额外资源

Node.js Release Schedule - Check oldest maintained LTS
Bunchee Documentation - Build tool
Vitest Documentation - Test runner

Node.js版本发布计划 - 查看仍在维护的最旧LTS版本
Bunchee文档 - 构建工具
Vitest文档 - 测试运行器