How can I add documentation links to different packages without creating a circular dependency?

[AlexFrazer]

So here's the situation: I have a Form (@workspace/form) and a FormField (@workspace/form-field) package and I want to cross-reference each in each other's documentation and inline hinting. My goal, ultimately, is to have inline documentation with links like so:

I initially implemented this by installing the dependency as a dev dependency in the package which I wanted to add documentation for

import { type Form } from "@workspace/form";
import { type Input } from "@workspace/input";
import { type Label } from "@workspace/label";

/**
* ### FormField
* 
* Used with a {@link Input} and {@link Label} to create a form field
* Should be placed inside a {@link Form} otherwise a warning will be emitted.
*/
export default function FormField() {}

However, this created a circular dependency if I want to cross-reference this documentation

import { type FormField } from "@workspace/form-field";

/**
* ### Form
*
* Defines a Form context
* Use with {@link FormField} to define a field
*/
export default function Form() {}

I tried using a dynamic import, hoping it would work

/**
* ### Form
*
* Defines a Form context
* Use with {@link import("@workspace").FormField} to define a field
*/
export default function Form() {}

This doesn't seem to have worked.

Does anyone know a way to solve this problem?

[apoorva-01]

Two different things get called "circular dependency" here and they have different fixes, so the first thing is figuring out which one is actually yelling at you: your build/bundler, or Nx's enforce-module-boundaries lint.

If it's the build: the culprit is import { type Form } with the type inline. With verbatimModuleSyntax on, TS emits a bare import {} from "@workspace/form" for that, which is a real side-effect import that stays in the output. Both files do it and you've got an actual runtime cycle. Move type out to the front of the import:

import type { FormField } from "@workspace/form-field";

Top-level import type gets erased completely, no import left in the emitted JS. And {@link FormField} still resolves for hover and go-to-def, because link resolution only needs the symbol in scope, not a value import. So your inline docs keep working and the cycle's gone.

Side note, your {@link import("@workspace").FormField} attempt was never going to resolve. Wrong subpath (that symbol lives in @workspace/form-field, not the @workspace barrel), but the bigger issue is TS's {@link} doesn't follow import("...").X type queries at all. It just prints them as literal text, no navigation. So there's no import-free way to get editor links, the symbol has to be imported somehow and a type import is the cheapest way to do it.

If it's the Nx lint instead: Nx counts type-only imports in its project graph too, and there's no flag to exclude them (that was #9083, closed keeping the behavior). Since the cycle is types-only and gone from the build output, I'd just // eslint-disable-next-line @nx/enforce-module-boundaries on the two import lines rather than restructure around what isn't a real runtime cycle.