@microsoft/api-extractor

What is @microsoft/api-extractor?

@microsoft/api-extractor is a tool for managing and analyzing the public API surface of a TypeScript library. It helps in generating API reports, creating API documentation, and ensuring API compatibility.

What are @microsoft/api-extractor's main functionalities?

Generate API Report

This feature allows you to generate an API report for your TypeScript library. The report includes details about the public API surface, which can be used for documentation and compatibility checks.

const { Extractor, ExtractorConfig } = require('@microsoft/api-extractor');
const path = require('path');

const configPath = path.join(__dirname, 'api-extractor.json');
const extractorConfig = ExtractorConfig.loadFileAndPrepare(configPath);
const extractorResult = Extractor.invoke(extractorConfig, {
  localBuild: true,
  showVerboseMessages: true
});

if (extractorResult.succeeded) {
  console.log('API Extractor completed successfully');
} else {
  console.error(`API Extractor completed with ${extractorResult.errorCount} errors`);
}

Generate API Documentation

This feature allows you to generate API documentation from the TypeScript library. The documentation is based on the public API surface and can be used for reference and development purposes.

const { Extractor, ExtractorConfig } = require('@microsoft/api-extractor');
const path = require('path');

const configPath = path.join(__dirname, 'api-extractor.json');
const extractorConfig = ExtractorConfig.loadFileAndPrepare(configPath);
const extractorResult = Extractor.invoke(extractorConfig, {
  localBuild: true,
  showVerboseMessages: true
});

if (extractorResult.succeeded) {
  console.log('API documentation generated successfully');
} else {
  console.error(`API documentation generation failed with ${extractorResult.errorCount} errors`);
}

Ensure API Compatibility

This feature allows you to ensure API compatibility by comparing the current API surface with a previously generated API report. It helps in maintaining backward compatibility and avoiding breaking changes.

const { Extractor, ExtractorConfig } = require('@microsoft/api-extractor');
const path = require('path');

const configPath = path.join(__dirname, 'api-extractor.json');
const extractorConfig = ExtractorConfig.loadFileAndPrepare(configPath);
const extractorResult = Extractor.invoke(extractorConfig, {
  localBuild: true,
  showVerboseMessages: true
});

if (extractorResult.succeeded) {
  console.log('API compatibility check passed');
} else {
  console.error(`API compatibility check failed with ${extractorResult.errorCount} errors`);
}

Other packages similar to @microsoft/api-extractor

typedoc

TypeDoc is a documentation generator for TypeScript projects. It generates API documentation directly from the source code, similar to how @microsoft/api-extractor generates API reports and documentation. However, TypeDoc focuses more on generating comprehensive documentation rather than managing API surfaces.

api-documenter

API Documenter is another tool from Microsoft that works in conjunction with API Extractor. It generates Markdown documentation from the API reports produced by API Extractor. While API Extractor focuses on analyzing and managing the API surface, API Documenter focuses on creating readable documentation.

tsdoc

TSDoc is a standard for documenting TypeScript code. It provides a consistent way to write comments and generate documentation. While TSDoc itself is not a tool, it is often used in conjunction with tools like TypeDoc and API Extractor to ensure consistent and comprehensive documentation.

README

api-extractor

A utility that analyzes a project, detects common JSDoc problems , and generates a report of the exported Public API.