Skip to content

Latest commit

 

History

History
71 lines (40 loc) · 4.3 KB

api-extractor.md

File metadata and controls

71 lines (40 loc) · 4.3 KB
Raw

API Extractor

What is API Extractor?

API Extractor is used for all npm packages we create (everything under packages/).

A video of introducing this tool to our repo, what it does and how to use it can be found here: https://msit.microsoftstream.com/video/9b0fa4ff-0400-85a9-4048-f1eb868919ad

The api-extractor used for a number of useful features:

  1. Ensures all API changes must be reviewed before merging into main.
    • Creates an api.md file containing the public API for a package. This must be checked in as part of a pull request.
    • This ensures we do not accidentally introduce breaking changes to the API, or accidentally introduce new functions/interfaces.
  2. Creates the rolled up .d.ts file for each package.
  3. Creates documentation for the API

How to run API Extractor

API Extractor is run as part of the build commands for each package. Running rush build -t "package-name" will trigger the api-extractor to run.

Configuration Files

The primary configuration file can be found here: common/config/api-extractor/api-extractor.json. Each package has their own api-extractor.json that extends from this.

Gating PRs

Pull Request builds check that the api extractor file was updated and will fail if it detects changes to any of the api.md files that were not checked in.

API Extractor feature information

API.md

This file is generated by the api-extractor when a package is built and is located under <repo>/packages/package-name/review/beta/<package-name>.api.md, e.g. https://github.com/Azure/communication-ui-library/blob/main/packages/calling-stateful-client/review/beta/calling-stateful-client.api.md

This file contains the public API for a package and also notes if no documentation exists for a given. It is mandatory to include changes to this file in your pull request. This ensures we don't introduce breaking changes to the API.

What does a breaking change look like in this file?

  1. You have removed a export from this file
  2. You have changed the signature for an existing export in this file (with exceptions detailed below)

What is a change to this file that is not a breaking change?

  1. You have added a new export to this file
    • However when adding new exports be sure they were intended additions! If we accidentally publish an internal function such as a helper function, we can no longer remove it in case a customer began using and relying on that export.
  2. You have added an extra optional parameter to the signature of an export.

.d.ts file

d.ts files are typescript declaration files. API Extractor creates a rolled up d.ts file for the whole package. After building your package you can see this file under dist/<package-name>.d.ts.

This allows us to export a single d.ts file as our types file, avoiding a messy export type tree, and also ensures only types reviewed in the api.md file are exported.

Documentation generation

Api Extractor is able to create complete API docs for the packages similar to what you would see on docs.microsoft.com. As of writing this we are using this for internal reviews of the API only. To try it out, in your terminal window navigate to a package and run rushx generate-doc. You can then open /docGen/index.md to check out the docs.

FAQs

Please add any problems you have to overcome with their solutions here for future reference.

My Pull Request build is failing with: Warning: You have changed the public API signature for this project.

This means you have uncommitted changes to the public API for that package. Ensure you run rush build -t "package-name", or rushx build inside the package directory, then add and commit the resultant api.md file to your pull request.

The api.md file changed but I didn't mean to change it - what do I do?

Take a look at what the changes are, changes to this file mean you have changed the public API for the package.

  • If you have added a new function to this file that means you have exported it publicly, check the index.ts files and ensure your function is not captured in a export * from '/file'.
  • If you have made a modification to an existing export, make sure to revert your change to the signature of that export.