As of 0.20, TypeDoc has limited support for TypeScript projects using project references and solution style tsconfig files. This support is limited since TypeDoc is currently unable to:
- Resolve type reference links between projects
- Properly link files to GitHub if they are in a child project of the root project.
How it works
For the most part, project reference support should just work, however if you have a tsconfig containing
the output might not quite match what you expect.
When given a solution style tsconfig whose program contains no files, TypeDoc will check for project references and create a program for each referenced project. Then, to find each entry point requested for documentation, it will check each of the programs in the order they are declared in the tsconfig file. If a file is present in multiple programs, only the file in the first program will be used.
As an example, in the project-references-demo project,
npx typedoc zoo/zoo.ts animals/index.ts will result in documentation where the createZoo function returns
Dog is not linked, even though animals/index.ts exports it. The cause of this is that the root tsconfig looks like this:
When TypeDoc looks for the entry points, it finds animals/index.ts in the second listed program before looking at ./zoo, while
Dog type used in
createZoo is from the third program. TypeDoc relies on TypeScript to link types, so is unable to resolve
types across programs, resulting in a broken link.
There are a couple possible fixes for this:
- Specify the "largest" projects first - if the tsconfig specified ./zoo first, then TypeDoc would find ./animals/index.ts in the zoo project, and links would work.
- Specify the tsconfig only for the root project expected to contain all symbols
npx typedoc --tsconfig zoo/tsconfig.json zoo/zoo.ts animals/index.tsworks as expected. This is usually the better solution since it allows TypeDoc to skip creating any unnecessary projects, making the type checking potentially significantly faster.