npm 包 extract-typedefs 使用教程

随着前端开发的快速发展，模块化已经成为了几乎每个项目的必需品。在面对大量的模块代码时，我们需要工具来帮助我们自动生成类型定义文件（TypeScript）和 API 文档。在这篇文章中，我们将介绍一个非常好用的 npm 包：extract-typedefs。

extract-typedefs 概述

extract-typedefs 是一个用于生成 TypeScript 类型定义文件的工具，它的主要特点是自动解析 JavaScript 源代码中的类型信息（包括 JSDoc 注释），以生成 TypeScript 的类型定义文件。

extract-typedefs 可读取 JavaScript 文件或 TypeScript 文件，生成对应的 TypeScript 类型定义文件。在自动生成类型定义文件的同时，它还可以生成方便的 API 文档。

安装

使用以下命令可以安装 extract-typedefs ：

npm install -D @microsoft/api-extractor typescript

命令解释：

• -D 表示将包安装到开发依赖里；
• @microsoft/api-extractor 是用于生成 API 文档的核心包；
• typescript 是用于编译 TypeScript 代码的包。

使用方法

简单使用

在安装好 extract-typedefs 后，我们就可以使用它来生成 TypeScript 类型定义文件和 API 文档了。

假设我们要生成的 TypeScript 类型定义文件名为 mytype.d.ts，那么命令如下：

npx extract-typedefs file1.js file2.js -o mytype.d.ts

• file1.js、file2.js 为需要生成类型定义文件的源文件；
• -o 表示输出路径，跟在后面的是输出的目标路径与文件名。

执行上述命令后，mytype.d.ts 就会生成了。

指定构建配置

extract-typedefs 也可以在项目中配置构建规则，具体方法如下：

1. 在项目根目录下新建 api-extractor.json 配置文件：

-- -------------------- ---- -------
-
  ---------- ------------------------------------------------------------------------------------------
  ------------------------- -------------------
  ----------- -
    ---------- ----
  --
  ------------ ---
  ------------ -
    ---------- -----
    ----------------- --------------------
  -
-

其中：

• mainEntryPointFilePath 是类型文件所在的目标路径（相对路径或绝对路径均可）；
• docModel 表示生成 API 文档；
• apiReport 表示生成 Markdown 格式的 API 文档。

1. 修改项目的 package.json，增加如下代码：

{
  "scripts": {
    "doc": "api-extractor run --local --verbose",
    "prepare": "npm run doc && tsc"
  }
}

这里的 doc 和 prepare 命令就是配置文件所提到的 API 文档生成命令和 TypeScript 编译命令。

现在，我们就可以在项目根目录中使用 npm run prepare 命令，自动编译 TypeScript，并生成 API 文档了。

示例代码

我们可以使用一个示例代码来演示如何使用 extract-typedefs。

示例代码目录结构如下：

example
├── api-extractor.json
├── lib
│   ├── greet.ts
│   └── index.ts
├── package-lock.json
├── package.json
└── tsconfig.json

其中，index.ts 如下所示：

export * from "./greet";

greet.ts 如下所示：

/**
 * @public
 */
export function greet(name: string): string {
  return `Hello, ${name}!`;
}

配置文件（api-extractor.json）如下所示：

-- -------------------- ---- -------
-
  ---------- ------------------------------------------------------------------------------------------
  ------------------------- -------------------
  ----------- -
    ---------- ----
  --
  ------------ ---
  ------------ -
    ---------- -----
    ----------------- --------------------
  -
-

执行命令后，可以得到如下目录结构：

-- -------------------- ---- -------
-------
--- ------------------
--- ---
-   --- --------
-   --- --------
--- -----------------
--- ------------
--- -------
-   --- --------
--- -------------
--- -----
    --- ----------

mylib.md 如下所示：

# API Report

## Functions

### greet

```typescript
export declare function greet(name: string): string;

Public function.

Parameters

Returns

Type: string

Version Information

ℹ️ API Extractor found 1 warning(s)!

-- -------------------- ---- -------

----- ---------- ---------- --- ---

-- --

------------------ ------------------------- ---------- ------- --- ----------------------------------

- ------------------------------------------------------------------------------ --------
------------------------------------------------------------------------------------------------------------------------