npm Library Setup with ESM

package.json

Overview

• 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

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

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

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

npm install -D typescript @types/node

tsconfig.json

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

.d.ts

React Component Libraries

npm install -D react @types/react

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

.js

File Structure

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

References

references/

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

Examples

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