TypeScript Library Development Skill

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 | | Package exports | references/package-exports.md | | tsconfig options | references/typescript-config.md | | Build configuration | references/build-tooling.md | | ESLint config | references/eslint-config.md | | API design patterns | references/api-design.md | | Type inference tricks | references/type-patterns.md | | Testing setup | references/testing.md | | Release workflow | references/release.md | | CI/CD setup | references/ci-workflows.md |

Loading Files

Consider loading these reference files based on your task:

[ ] references/project-setup.md - if starting a new TypeScript library project
[ ] references/package-exports.md - if configuring package.json exports or dual CJS/ESM
[ ] references/typescript-config.md - if setting up or modifying tsconfig.json
[ ] references/build-tooling.md - if configuring tsdown, unbuild, or build scripts
[ ] references/eslint-config.md - if setting up ESLint for library development
[ ] references/api-design.md - if designing public APIs, builder patterns, or plugin systems
[ ] references/type-patterns.md - if working with advanced TypeScript types or type inference
[ ] references/testing.md - if setting up vitest or writing tests for library code
[ ] references/release.md - if configuring release workflow or versioning
[ ] 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

Create project structure → load references/project-setup.md
Configure package.json exports → load references/package-exports.md
Set up build with tsdown → load references/build-tooling.md
Verify build: pnpm build && pnpm pack --dry-run — check output includes .mjs, .cjs, .d.ts
Add tests → load references/testing.md
Configure release → load references/release.md

Quick Start

// 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"]
}

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

Agent Skills: TypeScript Library Development

Install this agent skill to your local