TypeScript Academy · 课时

发布类型工具库

将自定义工具类型打包并分享到 npm

发布类型工具库 是 CoddyKit 上的免费 TypeScript Academy 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 TypeScript Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 TypeScript Academy 课程共包含 4 节课。

什么是类型实用工具库

类型实用工具库只导出 TypeScript 类型，不包含运行时代码。常见示例包括 type-fest、ts-essentials 和 utility-types。

// A type utility library exports types like:
export type DeepPartial<T> = T extends object
  ? { [K in keyof T]?: DeepPartial<T[K]> }
  : T;

项目结构

保持简单：只使用一个 src/index.ts 重新导出所有实用工具，并将 tsconfig.json 配置为仅生成声明。

// tsconfig.json
{
  "compilerOptions": {
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "dist",
    "strict": true
  }
}

仅包含类型的包的 package.json

将 main 和 types 字段设置为指向声明文件。将 sideEffects: false 设置为启用摇树优化。

{
  "name": "@myorg/type-utils",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "sideEffects": false,
  "files": ["dist"]
}

生成声明

运行 tsc 以生成 .d.ts 文件。对于仅包含类型的库，JS 输出为空或非常精简。

# Build declarations
npx tsc
# dist/index.d.ts is generated

版本管理与变更日志

请遵循语义化版本控制：破坏性类型变更会提升主版本，新增工具函数会提升次版本，修复问题会提升补丁版本。

# Bump version
npm version minor
# Generate changelog with conventional-changelog or changesets

发布到 npm

请使用 npm publish 或 pnpm publish。对于组织下的带作用域包，请确保您已登录并设置了作用域。

npm login
npm publish --access public
# or for private: npm publish --access restricted

TypeScript 版本兼容性

请记录您的工具函数所需的最低 TypeScript 版本。递归条件类型需要 TS 4.1 或更高版本，Awaited 从 TS 4.5 起内置。

// package.json peerDependencies
{
  "peerDependencies": {
    "typescript": ">=4.5"
  }
}

使用 tsd 测试类型

请使用 tsd 包编写类型级测试，让测试在持续集成期间运行，以确保您的工具函数行为正确。

import { expectType } from "tsd";
import type { DeepPartial } from "@myorg/type-utils";

expectType<DeepPartial<{ a: { b: number } }>>({ a: {} });

使用 TSDoc 编写文档

请为您的类型添加 /** */ JSDoc 注释。TypeDoc 等工具可以据此生成 API 文档。

/**
 * Makes all properties of T optional at every depth.
 * @example type A = DeepPartial<{ x: { y: number } }> // { x?: { y?: number } }
 */
export type DeepPartial<T> = ...

单仓库分发

在单仓库中，请将类型包发布为工作区包，以便其他应用通过 workspace:* 使用它，而不是通过 npm 使用。

// Other package's package.json
{
  "dependencies": {
    "@myorg/type-utils": "workspace:*"
  }
}

回顾：发布类型库

类型工具库应设置 emitDeclarationOnly: true，从 src/index.ts 导出类型，使用语义化版本控制，使用 tsd 测试，使用 TSDoc 编写文档，并发布到 npm 或工作区注册表。

快速检查

哪个 tsconfig 选项只生成 .d.ts 文件而不输出 JavaScript？

您学到的内容

发布类型工具库需要使用 emitDeclarationOnly、正确的 package.json 字段、使用 tsd 编写类型级测试、添加 TSDoc 注释以及采用语义化版本控制。您可以与社区或单仓库中的其他项目分享您的工具函数。

常见问题解答

「发布类型工具库」课时是免费的吗？

是的 — 「发布类型工具库」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 TypeScript Academy 课程的其余内容，请升级到 CoddyKit PRO。 TypeScript Academy 课程共包含 4 节课。

「发布类型工具库」这节课中我会学到什么？

将自定义工具类型打包并分享到 npm 你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 TypeScript Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 TypeScript Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「发布类型工具库」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 TypeScript Academy 课中编写并运行代码吗？

能。每节 TypeScript Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 TypeScript Academy