如何为纯JS项目接入TS并发布支持TS的JS+JSDoc类库？

针对你遇到的本地类型检查正常但NPM发布后下游TS无法识别类型的问题，以下是满足需求的两种方案：

最优方案：无需生成.d.ts，直接让TS解析JS+JSDoc类型 #

此方案完全符合「不生成声明文件、不重复src文件、不破坏工具链」的要求，开发者仍编辑src下的JS文件，下游可直接通过src路径导入并识别类型。

1. 调整tsconfig.json配置 #

确保TS能正确解析JS中的JSDoc，同时避免生成任何输出文件：

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "noEmit": true, // 核心：不生成任何输出，避免与src文件冲突
    "declaration": false,
    "rootDir": "./src",
    "baseUrl": "./",
    "moduleResolution": "node16", // 适配package.json的exports字段
    "target": "ES2020"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "types"]
}

2. 配置package.json，让下游TS找到类型 #

通过exports字段的通配符映射，覆盖根路径和子路径的类型解析：

{
  "name": "your-library",
  "version": "1.0.0",
  "main": "src/index.js",
  "types": "src/index.js", // 主入口类型指向JS文件，TS自动解析JSDoc
  "exports": {
    ".": {
      "types": "./src/index.js",
      "default": "./src/index.js"
    },
    "./*": {
      "types": "./src/*.js",
      "default": "./src/*.js"
    }
  },
  "type": "module", // 若为ES模块必须添加，CommonJS则移除
  "files": ["src/**/*"], // 发布时包含src所有文件
  "scripts": {
    "check": "tsc" // 本地类型检查脚本
  }
}

方案优势 #

• 彻底避免生成.d.ts带来的TS5055错误和文件重复问题
• 下游无论是根路径（import lib from 'your-library'）还是子路径（import { fn } from 'your-library/utils'）导入，TS都能通过exports映射找到对应JS文件并解析JSDoc类型
• 开发者仍在src目录编辑JS，本地通过npm run check做类型检查，完全不破坏原有工具链

备选方案：生成.d.ts但不重复src文件（兼容旧版TS） #

如果下游存在无法直接解析JS+JSDoc的旧版TS，可采用此方案，仅生成声明文件到独立目录，不复制JS文件。

1. 修改tsconfig.json，仅输出声明文件到types目录 #

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "declaration": true,
    "declarationDir": "./types", // 声明文件输出到独立目录
    "emitDeclarationOnly": true, // 核心：只生成.d.ts，不复制JS文件
    "rootDir": "./src",
    "moduleResolution": "node16",
    "target": "ES2020"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "types"]
}

2. 配置package.json映射类型路径 #

{
  "name": "your-library",
  "version": "1.0.0",
  "main": "src/index.js",
  "types": "types/index.d.ts",
  "exports": {
    ".": {
      "types": "./types/index.d.ts",
      "default": "./src/index.js"
    },
    "./*": {
      "types": "./types/*.d.ts",
      "default": "./src/*.js"
    }
  },
  "files": ["src/**/*", "types/**/*"],
  "scripts": {
    "build:types": "tsc",
    "check": "tsc --noEmit"
  }
}

方案优势 #

• 仅生成.d.ts文件，不重复src目录结构
• 下游通过exports映射找到对应声明文件，类型识别正常
• 本地开发用npm run check做类型检查，构建声明用npm run build:types，工具链不受影响

常见问题排查 #

1. 子路径类型不识别：确保package.json的exports通配符配置正确，且TS版本≥4.7（支持node16模块解析）
2. TS5055错误：确保declarationDir未指向src目录，且noEmit或emitDeclarationOnly配置正确，避免输出文件覆盖src
3. 发布后类型丢失：确认package.json的files字段包含了src（或types）目录，NPM发布时未遗漏文件

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