TypeScript转JavaScript时如何保留@typedef类型定义？

我有如下TypeScript代码：

/**
 * @typedef Foo
 * @type {Object}
 * @property {string} id
 */
type Foo = {
    id: string
}
/**
 * bar
 * @returns {Foo}
 */
function bar(): Foo {
    const foo:Foo = {id: 'foo'}
    return foo
}

使用Rollup或tsc转译为JavaScript时，Foo对应的@typedef JSDoc块会被自动移除，导致编辑器中bar函数的@returns{Foo} JSDoc无法正常生效。我希望转译后的代码能保留该JSDoc块，得到如下结果：

/**
 * @typedef Foo
 * @type {Object}
 * @property {string} id
 */

/**
 * bar
 * @returns {Foo}
 */
function bar() {
    const foo = { id: 'foo' };
    return foo;
}

请问有没有办法保留这个JSDoc块？

解决方案 #

1. 修改TypeScript编译配置 #

在tsconfig.json中设置removeComments: false，让TypeScript编译器保留所有注释，包括类型定义关联的JSDoc：

{
  "compilerOptions": {
    "removeComments": false,
    // 其他编译配置项...
  }
}

注意：该配置会保留代码中所有注释（包括普通单行/多行注释），如果仅需保留特定JSDoc，需结合其他方法。

2. 使用Rollup专用插件 #

如果用Rollup构建，可借助rollup-plugin-preserve-jsdoc插件精准保留目标JSDoc注释。安装插件后，在Rollup配置中启用：

import preserveJsdoc from 'rollup-plugin-preserve-jsdoc';
import typescript from '@rollup/plugin-typescript';

export default {
  // 其他Rollup配置项...
  plugins: [
    typescript(),
    preserveJsdoc()
  ]
};

3. 调整代码注释写法 #

将@typedef的JSDoc与类型定义做更紧密的绑定，避免编译器将其判定为可移除的类型注释，比如合并注释内容：

/**
 * @typedef {Object} Foo
 * @property {string} id
 */
type Foo = {
    id: string
}

这种写法能让编译器更准确识别该JSDoc为类型的文档注释，配合removeComments: false配置时更易被保留。

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