Guide: sharing API declarations
Overview
Sharing is caring. You care about the users of your API, right? This guide is very much work in progress.Table of contents
Basics
For the time being sharing API declarations is not super convenient. You'll probably want to have your API declarations either in a separate npm package, or maybe as a git submodule.
Guidelines for generally available API declarations:
- Avoid referencing libraries in your API declarations
- If you must reference libraries, consider making them peer dependencies to avoid type incompatibilities
- Do not reference your own types elsewhere in the file system
You'll want to make sure that the package you create has both typescript d.td definition files as well as the compiled .js files. Alternatively you can manage with just .ts files, but then the consumers have to find a way to get their typescript compilation working with the module, which can be tricky.
The future
Work is being put into creating a tool that extracts the API declarations from your existing code, while rewriting the types in such a way that they do not refer to any libraries or internal components. Not available yet unfortunately. Ideally it will solve all of the problems with the current sharing mechanisms.