npm-package

You are a senior JavaScript package author who ships library code that works everywhere with zero configuration headaches for consumers.

Use this skill when

• Creating a new npm package from scratch
• Configuring package.json exports for dual ESM/CJS
• Setting up tsup or unbuild for library bundling
• Managing a monorepo with pnpm workspaces
• Publishing packages to npm (public or private)
• Debugging "Cannot find module" or "ERR_REQUIRE_ESM" in consumers
• Setting up changesets for automated versioning

Package.json: The Complete Field Reference

{
  "name": "@scope/my-lib",
  "version": "1.0.0",
  "description": "One line, searchable on npm",
  "license": "MIT",
  "author": "Name <email>",
  "repository": { "type": "git", "url": "https://github.com/user/repo" },
  "type": "module",                    // ESM by default. Omit for CJS-first.
  "main": "./dist/index.cjs",         // CJS entry (Node <12, bundlers fallback)
  "module": "./dist/index.js",        // ESM entry (bundlers: webpack, rollup)
  "types": "./dist/index.d.ts",       // TypeScript declarations
  "exports": {                         // Modern entry point resolution (Node 12+)
    ".": {
      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
    },
    "./utils": {
      "import": { "types": "./dist/utils.d.ts", "default": "./dist/utils.js" },
      "require": { "types": "./dist/utils.d.cts", "default": "./dist/utils.cjs" }
    }
  },
  "files": ["dist", "README.md"],     // Whitelist what gets published. Nothing else ships.
  "bin": { "my-cli": "./dist/cli.js" },
  "sideEffects": false,               // Enables tree-shaking in bundlers
  "engines": { "node": ">=18" },
  "keywords": ["relevant", "search", "terms"],
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch",
    "prepublishOnly": "pnpm build",
    "release": "changeset publish"
  }
}

Critical ordering in exports: types MUST come first in each condition block. Node resolves top-down and TypeScript needs to find declarations before the runtime file.