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:

   bash

   npm init -y
   

2. •

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

3. •

   Install build and test tools:

   bash

   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-case files: Use kebab-case for file paths

TypeScript Setup

Install TypeScript and configure:

npm install -D typescript @types/node

Create tsconfig.json:

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

Bunchee automatically compiles TypeScript and generates .d.ts files.

React Component Libraries

Install React as dev dependency:

npm install -D react @types/react

Configure peerDependencies:

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

Best Practices

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

Common Patterns

ESM Import/Export

// 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.

File Structure

my-package/
├── package.json
├── src/
│   ├── index.js         # or index.ts
│   └── helpers.js
├── dist/                # Build output
└── 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

Examples

See examples/ directory for complete working examples:

• •JavaScript ESM package
• •TypeScript ESM package

Additional Resources

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