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
- Update version in package.json
- Build:
npm run build
- Test the package:
npm pack and inspect tarball
- 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
- references/tsconfig.md - tsconfig options explained
- references/exports.md - Package exports patterns
- references/publishing.md - npm publishing workflow
1---2name: typescript-library3description: Use when developing TypeScript npm packages including tsconfig, package.json exports, dual CJS/ESM builds, and publishing4---5
6# TypeScript Library Development
7
8## Quick Start
9
10```json
11// package.json
12{
13 "name": "my-library",
14 "version": "1.0.0",
15 "type": "module",
16 "main": "./dist/index.cjs",
17 "module": "./dist/index.js",
18 "types": "./dist/index.d.ts",
19 "exports": {
20 ".": {
21 "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
22 "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
23 }
24 },
25 "files": ["dist"]
26}
27```
28
29## tsconfig.json Essentials
30
31```json
32{
33 "compilerOptions": {
34 "target": "ES2022",
35 "module": "NodeNext",
36 "moduleResolution": "NodeNext",
37 "declaration": true,
38 "declarationMap": true,
39 "sourceMap": true,
40 "outDir": "dist",
41 "strict": true,
42 "esModuleInterop": true,
43 "skipLibCheck": true
44 },
45 "include": ["src"],
46 "exclude": ["**/*.test.ts"]
47}
48```
49
50## Key Practices
51
52- **Exports field**: Required for proper ESM/CJS dual support
53- **Types first**: In conditional exports, `types` must come before `default`
54- **Files array**: Only publish what's needed (dist, README, LICENSE)
55- **Declaration maps**: Enable go-to-definition in consuming projects
56- **Peer dependencies**: For frameworks/libraries users must also install
57
58## Publishing Checklist
59
601. Update version in package.json
612. Build: `npm run build`
623. Test the package: `npm pack` and inspect tarball
634. Publish: `npm publish` (or `npm publish --access public` for scoped)
64
65## Common Tools
66
67- **tsup**: Zero-config bundler for TypeScript libraries
68- **unbuild**: Build system with automatic CJS/ESM
69- **changesets**: Version management and changelogs
70
71## Reference Files
72
73- [references/tsconfig.md](references/tsconfig.md) - tsconfig options explained
74- [references/exports.md](references/exports.md) - Package exports patterns
75- [references/publishing.md](references/publishing.md) - npm publishing workflow
majiayu000