Automatically generate type declarations 🪄

[alexweininger]

We are currently manually maintaining an index.d.ts declaration file in each package.

Why this isn't good:

• We have to manually update declaration file -> easy to make mistakes
  • No checking to make sure something wasn't added
  • No checking to make sure types are valid and match the source
• Have to import types from '../../../index' -> ugly 😢

The TypeScript compiler can generate declaration files from source .ts files. It takes every exported source file [source].ts and generates a corresponding [source].d.ts declaration file. However, we often want to hide certain properties, methods, etc. from the public api of our libraries. Which isn't possible by only using tsc.

Currently, we declare an internal interface, and then declare a public interface in the declaration as a way of hiding internal things. This is cumbersome to write, and adds confusion in the source code.

And that's when the @microsoft/api-extractor package comes to save the day. 🦸

Their website has a great summary of the package. It can rollup generated declaration files into a single declaration file to include in the npm package. On top of that, it leverages TSDoc for some really nice features. For example, excluding things marked with @internal, or separating @beta declarations for developing new APIs.