npm Library Setup with ESM

This skill provides comprehensive guidance on setting up an npm library with package.json, with a preference for 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

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

Quick Start

1. Initialize your package:

   npm init -y
   

2. Configure for ESM by adding "type": "module" to package.json

3. Install build and test tools:

   npm install -D bunchee vitest
   

4. Create your source files in src/ and run npm run build

Essential Configuration

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

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

Key Principles

1. ESM-first: Use "type": "module" for pure ESM packages
2. Modern exports: Use exports field instead of deprecated module field
3. Zero-config bundling: Bunchee handles most configuration automatically
4. File extensions: Use explicit .js extensions in imports (even in TypeScript)
5. **Kebab-c...