/SKILL.md

name, description, license

name	description	license
ts-library	用于编写 TypeScript 库或 npm 包时的技能——涵盖项目初始化、package.json 导出配置、构建工具（tsdown/unbuild）、API 设计模式、类型推断技巧、测试以及发布到 npm。适用于打包配置、双 CJS/ESM 输出配置或发布工作流设置。	MIT

TypeScript 库开发

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

何时使用

• 开始一个新的 TypeScript 库（单体仓库或 monorepo）
• 配置 package.json 的双 CJS/ESM 导出
• 为库开发配置 tsconfig
• 选择构建工具（tsdown、unbuild）
• 设计类型安全的 API（builder、factory、plugin 模式）
• 编写高级 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（最小配置）
{
  "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 消费者
• moduleResolution: "Bundler" 用于现代 TypeScript
• 大部分构建使用 tsdown，复杂场景使用 unbuild
• 智能默认值：自动检测环境，不强制要求配置
• 支持摇树优化：惰性 getter，正确设置 sideEffects: false

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