Rollup API Extractor Plugin

0.2.5 · active · verified Wed Apr 22

The `rollup-plugin-api-extractor` package provides a Rollup plugin to seamlessly integrate `@microsoft/api-extractor` into TypeScript build workflows. It allows developers to generate and manage high-quality API declaration files (`.d.ts`) and API documentation reports directly within their Rollup build process. As of version 0.2.5, this plugin supports the latest features of API Extractor to enable consistent API surface definition and validation for libraries. It is actively maintained with relatively frequent minor updates since its initial release (0.2.2), making it a reliable choice for projects requiring robust type declaration bundling and API surface control. A key differentiator is its direct, configurable integration with Rollup, avoiding complex manual scripting for API Extractor execution.

Common errors

```
Error: [@microsoft/api-extractor] The API Extractor configuration file could not be found.
```
cause The `api-extractor.json` file is either missing, incorrectly named, or its path is not accessible/specified.

fix Run `npx api-extractor init` to generate `api-extractor.json` in the default location (`config/`) or provide the correct path via the `configFile` plugin option: `apiExtractor({ configFile: './your-config.json' })`.
```
TypeError: apiExtractor is not a function
```
cause The plugin's named export `apiExtractor` was incorrectly imported as a default export or through an improper CommonJS `require` statement.

fix Ensure you are using named import syntax: `import { apiExtractor } from 'rollup-plugin-api-extractor';` or for CommonJS: `const { apiExtractor } = require('rollup-plugin-api-extractor');`.
```
You must install rollup (>=2.63.0) and @microsoft/api-extractor (>=7.19.0) as peer dependencies.
```
cause One or both of the required peer dependencies (`rollup` and `@microsoft/api-extractor`) are not installed in your project.

fix Install the missing peer dependencies using `npm install --save-dev rollup @microsoft/api-extractor` or `yarn add --dev rollup @microsoft/api-extractor`.

Warnings

gotcha `@microsoft/api-extractor` and `rollup` are peer dependencies of this plugin and must be installed separately in your project.
Fix: Run `npm install --save-dev @microsoft/api-extractor rollup` or `yarn add --dev @microsoft/api-extractor rollup`.
gotcha For API Extractor to function correctly, your `tsconfig.json` must have `compilerOptions.declaration` and `compilerOptions.declarationMap` set to `true`.
Fix: Ensure `tsconfig.json` includes: `{ "compilerOptions": { "declaration": true, "declarationMap": true } }`.
gotcha The `types` or `typings` field in your `package.json` must accurately point to the main declaration file (`.d.ts`) generated by API Extractor (e.g., `lib/index.d.ts`).
Fix: Update `package.json`: `'types': 'path/to/your/main.d.ts'`.
gotcha The `api-extractor.json` configuration file must be initialized and its `mainEntryPointFilePath` property correctly configured to match your `package.json`'s `types` field.
Fix: Run `npx api-extractor init` to generate the file, then edit `api-extractor.json` to set `'mainEntryPointFilePath': '<projectFolder>/lib/index.d.ts'` (adjust path as needed).
gotcha If `api-extractor.json` is not located at the default path (`./config/api-extractor.json`), you must explicitly specify its path in the plugin options.
Fix: Pass `{ configFile: './path/to/your/api-extractor.json' }` to the `apiExtractor()` plugin call in your `rollup.config.js`.

Install

npm install rollup-plugin-api-extractor npm
yarn add rollup-plugin-api-extractor yarn
pnpm add rollup-plugin-api-extractor pnpm

Imports

apiExtractor
wrong:
```
import apiExtractor from 'rollup-plugin-api-extractor';
```
correct:
```
import { apiExtractor } from 'rollup-plugin-api-extractor';
```
The `apiExtractor` function is a named export and must be imported using destructuring. This package is typically used in Rollup configuration files which usually support ESM syntax.
apiExtractor (CJS)
wrong:
```
const apiExtractor = require('rollup-plugin-api-extractor');
```
correct:
```
const { apiExtractor } = require('rollup-plugin-api-extractor');
```
For CommonJS environments (e.g., older Node.js Rollup configs), named exports are accessed via destructuring from the `require` call.
Plugin Options Type
```
import { ApiExtractorPluginOptions } from 'rollup-plugin-api-extractor';
```
TypeScript users can import the `ApiExtractorPluginOptions` type for better type checking when configuring the plugin.

Quickstart

This quickstart demonstrates integrating `rollup-plugin-api-extractor` into a basic Rollup configuration for a TypeScript project, bundling `src/index.ts` into ESM format and then processing declarations with API Extractor.

import typescript from '@rollup/plugin-typescript';
import { apiExtractor } from 'rollup-plugin-api-extractor';

export default {
  input: 'src/index.ts',
  output: {
    dir: 'dist',
    format: 'esm'
  },
  plugins: [
    typescript(),
    apiExtractor({
      // Optional: Specify a custom config file path if not at './config/api-extractor.json'
      // configFile: './api-extractor.json'
      // Optional: Override config settings directly
      // configuration: {
      //   mainEntryPointFilePath: '<projectFolder>/lib/index.d.ts'
      // }
    })
  ]
};

view raw JSON →