Rollup-plugin-api-extractor NPM

rollup-plugin-api-extractor

This is a rollup plugin to integrate @microsoft/api-extractor into the rollup build system.

Usage

Install the package and @microsoft/api-extractor with npm (or yarn):

npm

npm install --save-dev rollup-plugin-api-extractor @microsoft/api-extractor

yarn

yarn add --dev rollup-plugin-api-extractor @microsoft/api-extractor

Add to rollup config:

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()],
  },
];

Configure for api-extractor

The below is based on the example at https://api-extractor.com/pages/setup/invoking/:

Add the typings or types field to package.json:

{
  // ...
  "types": "lib/index.d.ts"
  // ...
}

Make sure "declaration": true and "declarationMap": true are in set in your tsconfig.json.

Generate the api-extractor configuration:

npx

npx api-extractor init

yarn

yarn api-extractor init

Update the generated api-extractor.json so that mainEntryPointFilePath matches the typings/types field in package.json

"mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",

If api-extractor.json is not in the config folder update the apiExtractor() in your rollup.config.js to reference it:

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({
        configFile: "./api-extractor.json",
      }),
    ],
  },
];

Plugin Configuration Options

The plugin Options are as follows:

Option	Default	Description
configFile	'./config/api-extractor.json'	The path to the api extractor configuration file.
configuration		the configuration for `@microsoft/api-extractor`. If both `configFile` and this are specified, parameters specified here will override those in the configuration file.
local	false	Indicates that API Extractor is running as part of a local build. Equates to `--local` in api-extractor run command line.
verbose	false	Show additional informational messages in the output. Equates to `--verbose` in api-extractor run command line.
diagnostics	false	Show diagnostic messages used for troubleshooting problems with API Extractor. Equates to `--diagnostics` in api-extractor run command line.
typescriptFolder		Used to override the typescript compiler folder for `@microsoft/api-extractor`. Equates to `--typescript-compiler-folder` in api-extractor run command line.

`configuration` and `configFile` parameters

As mentioned above, the plugin can take the @microsoft/api-extractor configuration as part of the options for it. If no configFile is specified the below are the minimum configuration parameters currently require by @microsoft/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({
        configuration: {
          projectFolder: ".",
          compiler: {
            tsconfigFilePath: "<projectFolder>/tsconfig.json",
          },
        },
      }),
    ],
  },
];

If configFile and configuration are both specified, the configuration file is read with the configuration acting as an overlay or override of the parameters that are in the file.

Why?

While there are already rollup plugins for rolling up the type definitions in a package, @microsoft/api-extractor does more. In addition, @microsoft/api-extractor has the ability to "trim" the type definitions to excluded APIs not meant for external consumption.