Rush StackShopBlogEvents
跳到主要内容

API Extractor plugin

Plugin package:@rushstack/heft-api-extractor-plugin
Plugin name:api-extractor-plugin implemented by ApiExtractorPlugin.ts
Plugin config file:api-extractor-task.json
heft.json options:(none)

This plugin invokes the API Extractor tool which reads TypeScript declarations (.d.ts files) as inputs and produces three types of outputs:

1. API Report - API Extractor can trace all exports from your project's main entry point and generate a report to be used as the basis for an API review workflow.

2. .d.ts Rollups - Similar to how Webpack can "roll up" all your JavaScript files into a single .js file for distribution, API Extractor can roll up your TypeScript declarations into a single .d.ts file.

3. API Documentation - API Extractor can generate a "doc model" JSON file for each of your projects. This JSON file contains the extracted type signatures and doc comments. The api-documenter companion tool can use these files to generate an API reference website, or you can use them as inputs for a custom documentation pipeline.

See the API Extractor documentation for details about how it works.

When to use it

We recommend to use API Extractor for every TypeScript library project, especially if it is published as an NPM package.

package.json dependencies

If you are using a standard rig such as @rushstack/heft-node-rig or @rushstack/heft-web-rig, then API Extractor will already be loaded and configured.

Otherwise, you'll need to add these packages to your project:

# If you are using Rush, run this shell command in your project folder:
rush add --package @rushstack/heft-api-extractor-plugin --dev
rush add --package @microsoft/api-extractor --dev

Configuration

If API Extractor is not already being provided by a rig, your heft.json config file could invoke it like in this example:

<project folder>/config/heft.json

{
"$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
. . .
"phasesByName": {
"build": {
"cleanFiles": [{ "sourcePath": "dist" }, { "sourcePath": "lib" }, { "sourcePath": "lib-commonjs" }],
"tasksByName": {
"typescript": {
"taskPlugin": {
"pluginPackage": "@rushstack/heft-typescript-plugin"
}
},
"api-extractor": {
"taskDependencies": ["typescript"],
"taskPlugin": {
"pluginPackage": "@rushstack/heft-api-extractor-plugin"
}
},
. . .
}
}
. . .
}
}

Heft looks for API Extractor's config file config/api-extractor.json. This file can be created by invoking the api-extractor init command. This file is riggable.

For advanced scenarios, the optional api-extractor-task.json config file provides some additional Heft-specific settings.

See also