When using packages allow allow linking to types between different packages

[patrickarlt]

Search Terms

package, link

Problem

I have a large monorepo with several packages that include a shared types package to handle common interfaces that are used multiple packages. I have a super minimal reproduction of the issue in https://github.com/patrickarlt/typedoc-cross-link-packages-demo/ and hosted the TypeDoc at https://patrickarlt.github.io/typedoc-cross-link-packages-demo/index.html

Essentially the following is happening:

// export shared types from packages/shared/index.ts
export interface IceCream {
  flavor: Flavors;
}

export enum Flavors {
  chocolate,
  vanilla,
}

// import shared types and use them in packages/factory/index.ts
import { IceCream, Flavors } from "../shared";

// ideally `Flavors` and `IceCream` would link to the doc in the shared package but they do not.
export function make(flavor: Flavors): IceCream {
  return {
    flavor: flavor,
  };
}

However if I re-export the shared types they get documented but as a part of the package they are exported from not the shared package.

// import shared types and use them in packages/store/index.ts
import { IceCream, Flavors } from "../shared";

// re-export so they get documented as a part of the store package
export { IceCream, Flavors } from "../shared";

export function serve(flavor: Flavors): IceCream {
  return {
    flavor: flavor,
  };
}

Suggested Solution

If a file in a package imports from another package that is in the packages array then any doc using that type should link to that package in the generated documentation.

I would also be totally fine if there was a plugin that provided this behavior but I couldn't fine one and it seems like this should be core behavior since I am documenting the shared package with TypeDoc.

If this should go in a plugin I would be happy for some pointers beyond the existing plugin doc to get started developing a plugin that does this.

[Gerrit0]

This is definitely something that should live in TypeDoc itself - unfortunately it's kind of tricky to do... right now we resolve references based on symbols, and TS uses different symbols for each program (package)

[patrickarlt]

@Gerrit0 I saw that when I was messing around with this a bit more yesterday. Is this something you would need fixed in the TypeScript compiler before it could be fixed in TypeDoc? I don't mind exporting the extra interfaces but at scale someone will forget to export and it won't get linked. FWIW api-extractor doesn't do this either so it might just be too difficult.

The workaround to simply re-export works for now but it would be great if this could be resolved in the future.

[Gerrit0]

No, the compiler is behaving exactly as it should. The programs are entirely separate so they really should be separate. This resolution is something TypeDoc would have to do, likely by making some assumptions about things with the same name/position in a file with the same basename being the same symbol

Something that might possibly work well is setting up a separate project with project references to each of your packages and having an entry point which re-exports each package, which if TS resolves references properly, might let the types be linked

[efokschaner]

I ran in to something possibly similar when we implemented "packages" support. See "Inter-package references" in https://github.com/TypeStrong/typedoc/pull/1567#issue-613031115

I wondered if declaration maps could solve this (https://www.typescriptlang.org/tsconfig#declarationMap) I think that's how similar tooling such as vscode makes the Inter-package references work smoothly.

[Gerrit0]

declaration maps are definitely going to be part of the answer, but they aren't sufficient without some additional work to stop using symbols.

[haltman-at]

We're having a similar problem. I forget the details of our workaround for this, but it's fairly hacky and involves relying on the discouraged type resolution step 4. Just chiming in to say it would be nice to have a proper solution for this.

[Gerrit0]

Going to close this one in favor of #1835