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
Loading Files
Consider loading these reference files based on your task:
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