ts-library

TypeScript 库开发

从研究 unocss、shiki、unplugin、vite、vitest、vueuse、zod、trpc、drizzle-orm 等项目中提取的高质量 TypeScript 库编写模式。

适用场景

• 开始开发新的 TypeScript 库（单仓库或 monorepo）
• 设置 package.json 导出以支持 CJS/ESM 双格式
• 配置用于库开发的 tsconfig
• 选择构建工具（tsdown、unbuild）
• 设计类型安全的 API（builder、factory、插件模式）
• 编写高级 TypeScript 类型
• 设置 vitest 以测试库
• 配置发布工作流和 CI

Nuxt 模块开发： 使用 nuxt-modules 技能

快速参考

正在处理……	加载文件
新项目设置	references/project-setup.md
包导出	references/package-exports.md
tsconfig 选项	references/typescript-config.md
构建配置	references/build-tooling.md
ESLint 配置	references/eslint-config.md
API 设计模式	references/api-design.md
类型推断技巧	references/type-patterns.md
测试设置	references/testing.md
发布工作流	references/release.md
CI/CD 设置	references/ci-workflows.md

加载文件

请根据任务考虑加载以下参考文件：

• references/project-setup.md - 如果要开始一个新的 TypeScript 库项目
• references/package-exports.md - 如果要配置 package.json 导出或 CJS/ESM 双格式
• references/typescript-config.md - 如果要设置或修改 tsconfig.json
• references/build-tooling.md - 如果要配置 tsdown、unbuild 或构建脚本
• references/eslint-config.md - 如果要为库开发设置 ESLint
• references/api-design.md - 如果要设计公共 API、builder 模式或插件系统
• references/type-patterns.md - 如果要处理高级 TypeScript 类型或类型推断
• references/testing.md - 如果要设置 vitest 或为库代码编写测试
• references/release.md - 如果要配置发布工作流或版本管理
• references/ci-workflows.md - 如果要设置 GitHub Actions 或 CI/CD 流水线

请勿一次性加载所有文件。 只加载与当前任务相关的文件。

新建库工作流

1. 创建项目结构 → 加载 references/project-setup.md
2. 配置 package.json 导出 → 加载 references/package-exports.md
3. 使用 tsdown 设置构建 → 加载 references/build-tooling.md
4. 验证构建：pnpm build && pnpm pack --dry-run — 检查输出是否包含 .mjs、.cjs、.d.ts
5. 添加测试 → 加载 references/testing.md
6. 配置发布 → 加载 references/release.md

快速开始

// 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,
})

核心原则

• ESM 优先：使用 "type": "module"，输出 .mjs
• 双格式：始终支持 CJS 和 ESM 使用者
• 现代 TypeScript 使用 moduleResolution: "Bundler"
• 大多数构建使用 tsdown，复杂场景使用 unbuild
• 智能默认值：检测环境，不强制配置
• 支持摇树优化：使用惰性 getter，并正确设置 sideEffects: false

令牌效率：主技能约 300 个令牌，每个参考约 800–1200 个令牌