typedoc: Cross-package references in monorepository not working
Search terms
monorepository entrypointStrategy packages reference
Expected Behavior
Cross-package references should “work” when generating documentation for several packages in a monorepository (using yarn workspaces), with an entrypointStrategy set to packages.
Actual Behavior
Cross-package references yield a warning:
A, defined at packages/a/lib/index.d.ts:3, is referenced by @typedoc-packages-missing-export/b.B.__type.a but not included in the documentation.
And the resulting documentation does not have hyperlinks for such references.
Steps to reproduce the bug
Here is an example repository to reproduce the bug: https://github.com/nlepage/typedoc-packages-missing-export
Environment
- Typedoc version: 0.22.10
- TypeScript version: 4.5.4
- Node.js version: 14.17.0
- OS: Linux
About this issue
- Original URL
- State: closed
- Created 2 years ago
- Comments: 20 (8 by maintainers)
Links to this issue
Commits related to this issue
- Fix typedoc out-of-memory crashes. Typedoc has issues with monorepo support using lots of memory. See #356 and https://github.com/TypeStrong/typedoc/issues/1835. This avoids the crash in two differ... — committed to act-now-coalition/act-now-packages by mikelehen 2 years ago
- Add TypeDoc to lisk-transactions (#7909) ### What was the problem? This PR resolves #7901 Please note there is currently a bug in TypeDoc with the effect that references between packages are ... — committed to LiskHQ/lisk-sdk by Tschakki a year ago
- [IGNORE] Add simple typedoc setup I have been struggling to keep track of what Perses exports from the various UI packages, which can make it tricky to figure out breaking changes when things are ref... — committed to perses/perses by juliepagano a year ago
- [IGNORE] Add simple typedoc setup (#1056) I have been struggling to keep track of what Perses exports from the various UI packages, which can make it tricky to figure out breaking changes when thin... — committed to perses/perses by juliepagano a year ago
Hey @Gerrit0
I made a plugin to solve the problem: nlepage/typedoc-plugin-resolve-crossmodule-references. Not sure about all of it, but it works fine for the basic cases. Here is an example of generated documentation where types from a module
areference a typeBfrom a moduleb. It is published on npm.I’m not sure if it can help with project references as I’m not familiar with these.
Let me know if it is something you would like to integrate in TypeDoc itself. It needs only one new dependency (plus a transitive one): convert-source-map.
v0.24.0 made a ton of changes, including a fix for this. Types are now serialized with their location rather than relying on object identity, and therefore can be resolved even across packages
typedoc-plugin-resolve-crossmodule-references is now archived and deprecated on npm, thanks for all your hard work @Gerrit0 !
@Tschakki I’ll have a look, could you open an issue on the plugin’s repository thanks https://github.com/nlepage/typedoc-plugin-resolve-crossmodule-references
@phihochzwei I published a new release of the plugin, let me know if it works for you.
I think that’s definitely a promising path forward! I’m probably not going to have time this weekend to look at it in as much detail as it deserves, but it’s something I’m absolutely interested in pursuing. I’d like to avoid the extra resolution step if possible, (by storing reference targets by file/location?)
This happens for the same reason it happens with project references. TypeDoc creates a new program for each monorepo, and symbols between programs are completely separate… but references are resolved by symbol equality.
I think this could be resolved by changing symbols so that they are compared by source location (with mapping… so
declarationMapwould have to be turned on), but haven’t gotten around to trying to make that work yet.