typescript-library

mcclowes's avatarfrom mcclowes

Use when developing TypeScript npm packages including tsconfig, package.json exports, dual CJS/ESM builds, and publishing

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 23, 2025
[Developer Tools]

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for developing, configuring, and publishing professional TypeScript npm packages. It solves the complexity of modern JavaScript distribution by offering standardized templates for dual CJS/ESM builds, optimized tsconfig settings, and precise package.json export configurations to ensure cross-environment compatibility.

Use Cases

  • Case 1: Scaffolding a new TypeScript library with modern 'NodeNext' module resolution and strict type-checking.
  • Case 2: Configuring dual-build support (ESM and CommonJS) to ensure your package works seamlessly in both legacy and modern Node.js environments.
  • Case 3: Setting up complex 'exports' maps in package.json to correctly expose subpaths and type definitions.
  • Case 4: Streamlining the npm publishing workflow, including build verification, tarball inspection, and version management.
nametypescript-library
descriptionUse when developing TypeScript npm packages including tsconfig, package.json exports, dual CJS/ESM builds, and publishing

TypeScript Library Development

Quick Start

// package.json
{
  "name": "my-library",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
    }
  },
  "files": ["dist"]
}

tsconfig.json Essentials

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"],
  "exclude": ["**/*.test.ts"]
}

Key Practices

  • Exports field: Required for proper ESM/CJS dual support
  • Types first: In conditional exports, types must come before default
  • Files array: Only publish what's needed (dist, README, LICENSE)
  • Declaration maps: Enable go-to-definition in consuming projects
  • Peer dependencies: For frameworks/libraries users must also install

Publishing Checklist

  1. Update version in package.json
  2. Build: npm run build
  3. Test the package: npm pack and inspect tarball
  4. Publish: npm publish (or npm publish --access public for scoped)

Common Tools

  • tsup: Zero-config bundler for TypeScript libraries
  • unbuild: Build system with automatic CJS/ESM
  • changesets: Version management and changelogs

Reference Files