TypeScript recently introduced the @link tag in JSDoc comments. The documentation is here.

However, @link only generates an actual link if the TypeScript compiler knows the link target. In other words, whatever I link to must either be declared within the same file or imported. This isn't always the case, however. Take this (made-up) example:

wheel.ts

/** A wheel for use with a {@link Car}. */
export interface Wheel {
  // ...
}

In this example, the JSDoc comment in wheel.ts references a type Car that is defined in a separate file, car.ts. Because wheel.ts doesn't import car.ts, TypeScript doesn't know what @link Car points to. As a result, it can't display a proper link for Car when displaying the documentation in VS Code:

So my question is: How can I tell TypeScript where to find the definition of Car?

I've tried the following approaches:

1. Regular import

Adding import { Car } from './car'; to the top of wheel.ts solves the problem and creates an actual link to Car (note how "Car" has turned blue now):

However, it leads to the TypeScript error "'Car' is declared but its value is never read. (6133)" on the import line. TypeScript doesn't seem to consider the @link tag an actual usage of the imported type.

I can add // @ts-ignore above the import to tell TypeScript to ignore the error. But that seems pretty ugly to me.

2. Type import

Instead of a regular import, I can use a type import: import type { Car } from './car';. The result is the same: The link works, but I get a TypeScript error.

3. Inline import

TypeScript supports type imports within JSDoc comments. So I tried the following syntax:

/** A wheel for use with a {@link import("./car").Car}. */

However, it seems that TypeScript doesn't evaluate imports within links:

4. Typedef comment

I tried importing the type as follows:

/** @typedef {import('./car').Car} Car */

/** A wheel for use with a {@link Car}. */
export interface Wheel {
  // ...
}

However, this didn't create a link, either.