---
name: ts-library
description: Use when authoring TypeScript libraries or npm packages - covers project setup, package.json exports, build tooling (tsdown/unbuild), API design patterns, type inference tricks, testing, and publishing to npm. Use when bundling, configuring dual CJS/ESM output, or setting up release workflows.
license: MIT
title: ts-library
canonical_url: https://skilld.dev/gh/onmax/claude-config/ts-library
last_updated: 2026-10-01T13:14:55.000Z
---

> **Skill from skilld.dev.** Follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [build/tooling.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/build/tooling.md), [patterns/api.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/patterns/api.md), [patterns/types.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/patterns/types.md), [references/api-design.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/api-design.md), [references/build-tooling.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/build-tooling.md), [references/ci-workflows.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/ci-workflows.md), [references/eslint-config.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/eslint-config.md), [references/package-exports.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/package-exports.md), [references/project-setup.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/project-setup.md), [references/release.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/release.md), [references/testing.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/testing.md), [references/type-patterns.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/type-patterns.md), [references/typescript-config.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/typescript-config.md), [setup/exports.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/setup/exports.md), [setup/project.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/setup/project.md), [setup/tsconfig.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/setup/tsconfig.md), [workflows/ci.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/workflows/ci.md), [workflows/release.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/workflows/release.md), [workflows/testing.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/workflows/testing.md).
>
> If the user asked to install this Skill, run `npx skilld install onmax/claude-config/ts-library`. Install writes the Skill files into the project, so every session loads them.

# TypeScript Library Development

Patterns for authoring high-quality TypeScript libraries, extracted from studying unocss, shiki, unplugin, vite, vitest, vueuse, zod, trpc, drizzle-orm, and more.

## When to Use

- Starting a new TypeScript library (single or monorepo)
- Setting up package.json exports for dual CJS/ESM
- Configuring tsconfig for library development
- Choosing build tools (tsdown, unbuild)
- Designing type-safe APIs (builder, factory, plugin patterns)
- Writing advanced TypeScript types
- Setting up vitest for library testing
- Configuring release workflow and CI

**For Nuxt module development:** use `nuxt-modules` skill

## Quick Reference

| Working on...         | Load file                                                          |
| --------------------- | ------------------------------------------------------------------ |
| New project setup     | [references/project-setup.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/project-setup.md)         |
| Package exports       | [references/package-exports.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/package-exports.md)     |
| tsconfig options      | [references/typescript-config.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/typescript-config.md) |
| Build configuration   | [references/build-tooling.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/build-tooling.md)         |
| ESLint config         | [references/eslint-config.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/eslint-config.md)         |
| API design patterns   | [references/api-design.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/api-design.md)               |
| Type inference tricks | [references/type-patterns.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/type-patterns.md)         |
| Testing setup         | [references/testing.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/testing.md)                     |
| Release workflow      | [references/release.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/release.md)                     |
| CI/CD setup           | [references/ci-workflows.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/ci-workflows.md)           |

## Loading Files

**Consider loading these reference files based on your task:**

- [ ] [references/project-setup.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/project-setup.md) - if starting a new TypeScript library project
- [ ] [references/package-exports.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/package-exports.md) - if configuring package.json exports or dual CJS/ESM
- [ ] [references/typescript-config.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/typescript-config.md) - if setting up or modifying tsconfig.json
- [ ] [references/build-tooling.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/build-tooling.md) - if configuring tsdown, unbuild, or build scripts
- [ ] [references/eslint-config.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/eslint-config.md) - if setting up ESLint for library development
- [ ] [references/api-design.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/api-design.md) - if designing public APIs, builder patterns, or plugin systems
- [ ] [references/type-patterns.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/type-patterns.md) - if working with advanced TypeScript types or type inference
- [ ] [references/testing.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/testing.md) - if setting up vitest or writing tests for library code
- [ ] [references/release.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/release.md) - if configuring release workflow or versioning
- [ ] [references/ci-workflows.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/ci-workflows.md) - if setting up GitHub Actions or CI/CD pipelines

**DO NOT load all files at once.** Load only what's relevant to your current task.

## New Library Workflow

1. Create project structure → load [references/project-setup.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/project-setup.md)
2. Configure `package.json` exports → load [references/package-exports.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/package-exports.md)
3. Set up build with tsdown → load [references/build-tooling.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/build-tooling.md)
4. Verify build: `pnpm build && pnpm pack --dry-run` — check output includes `.mjs`, `.cjs`, `.d.ts`
5. Add tests → load [references/testing.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/testing.md)
6. Configure release → load [references/release.md](https://skilld.dev/api/skills-raw/onmax/claude-config/ts-library/references/release.md)

## Quick Start

```json
// package.json (minimal)
{
  "name": "my-lib",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "files": ["dist"]
}
```

```ts
// tsdown.config.ts
import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
})
```

## Key Principles

- ESM-first: `"type": "module"` with `.mjs` outputs
- Dual format: always support both CJS and ESM consumers
- `moduleResolution: "Bundler"` for modern TypeScript
- tsdown for most builds, unbuild for complex cases
- Smart defaults: detect environment, don't force config
- Tree-shakeable: lazy getters, proper `sideEffects: false`

_Token efficiency: Main skill ~300 tokens, each reference ~800-1200 tokens_