如何在NX包中添加JSDoc且避免产生循环依赖？

方案1：使用JSDoc完整包路径链接（无需导入类型） #

直接在JSDoc的{@link}中指定目标组件的完整包标识符，不需要在代码中导入对方包的类型，彻底避免循环依赖。

修改@workspace/form-field的代码：

/**
 * ### FormField
 * 
 * Use with {@link @workspace/form#Form}
 */
export default function FormField() {}

修改@workspace/form的代码：

/**
 * ### Form
 * 
 * You should use {@link @workspace/form-field#FormField} in a form
 */
export default function Form() {}

文档生成工具（如TypeDoc、Compodoc）会根据完整路径定位到目标组件，同时代码层面没有任何跨包依赖，不会触发NX的循环依赖检测。

方案2：抽离共享类型包（需类型检查场景） #

如果需要在代码中导入对方组件的类型用于类型校验，可以把共享类型抽离到独立的公共包，让两个组件包都依赖这个公共包，而非互相依赖。

1. 创建@workspace/shared-types包，导出组件类型：

// @workspace/shared-types/src/index.ts
export type Form = typeof import("@workspace/form").default;
export type FormField = typeof import("@workspace/form-field").default;

2. 在@workspace/form和@workspace/form-field中安装@workspace/shared-types，并导入类型：

// @workspace/form-field/src/index.ts
import type { Form } from "@workspace/shared-types";

/**
 * ### FormField
 * 
 * Use with {@link Form}
 */
export default function FormField() {}

// @workspace/form/src/index.ts
import type { FormField } from "@workspace/shared-types";

/**
 * ### Form
 * 
 * You should use {@link FormField} in a form
 */
export default function Form() {}

这种方式既满足类型导入需求，又通过单向依赖公共包避免了循环，同时JSDoc的{@link}能正常识别类型并生成链接。

方案3：仅类型导入（局限性较大） #

如果仅使用import type导入对方类型，TypeScript编译时会移除这些导入语句，但NX的依赖分析仍可能将其识别为跨包依赖，从而标记循环。仅在依赖检测宽松的场景下可用：

// @workspace/form-field/src/index.ts
import type { Form } from "@workspace/form";

/**
 * ### FormField
 * 
 * Use with {@link Form}
 */
export default function FormField() {}

内容的提问来源于stack exchange，提问作者corvid