如何为NPM库入口生成单一声明文件及优化接口声明导入问题

针对你遇到的两个问题，我分两部分给出具体的配置和解决办法：

一、仅生成入口文件的单一声明文件 #

要实现只输出库入口对应的index.d.ts，而非每个模块单独的.d.ts，通常需要结合TypeScript配置和打包工具的类型合并能力，下面是两种常用实现方式：

方式1：使用TypeScript 5.0+原生打包功能 #

TypeScript 5.0及以上版本新增了--declarationBundle选项，可直接将所有关联声明合并为单个文件：

1. 在tsconfig.json中配置：

{
  "compilerOptions": {
    "declaration": true,
    "declarationBundle": "./dist/index.d.ts", // 指定单一声明文件输出路径
    "emitDeclarationOnly": true, // 仅生成声明文件，不编译JS代码
    "outDir": "./dist",
    "module": "ESNext",
    "target": "ES6"
  },
  "include": ["index.ts"] // 仅编译入口文件
}

2. 执行编译命令：

tsc

TypeScript会自动将所有依赖模块的声明合并到指定的index.d.ts中，不会生成每个模块单独的声明文件。

方式2：使用Rollup + rollup-plugin-dts（兼容低版本TS） #

如果你的项目用Rollup打包JS文件，可以搭配rollup-plugin-dts插件合并声明：

1. 安装依赖：

npm install --save-dev rollup-plugin-dts @rollup/plugin-typescript

2. 创建rollup.config.js配置文件：

import dts from 'rollup-plugin-dts';
import typescript from '@rollup/plugin-typescript';

export default [
  // 打包JS文件的原有配置
  {
    input: 'index.ts',
    output: {
      file: 'dist/index.js',
      format: 'umd' // 可根据库需求选择umd/esm等格式
    },
    plugins: [typescript()]
  },
  // 打包声明文件的配置
  {
    input: 'index.ts',
    output: {
      file: 'dist/index.d.ts',
      format: 'es'
    },
    plugins: [dts()]
  }
];

3. 运行Rollup命令，会同时生成打包后的JS文件和合并后的单一声明文件，不会保留各模块的独立.d.ts。

二、将导入的接口内联到声明文件中 #

要让someInterface以内联形式存在于最终声明文件，而非保留导入语句，依赖类型合并工具的自动处理：

1. 若使用TypeScript 5.0+的--declarationBundle，它会自动将导入的类型内联到最终声明文件，无需额外配置。
2. 若使用rollup-plugin-dts，默认会分析所有依赖类型，将导入的接口、类型别名等合并到最终声明文件，替换原有的导入语句。

另外请确保types/index.d.ts正确导出接口：

// types/index.d.ts
export interface someInterface {
  // 接口字段定义
}

当你在业务模块中导入并使用该接口时，合并后的index.d.ts会直接包含someInterface的完整定义，而非保留import { someInterface } from './types'语句。

如果遇到部分类型未内联的情况，可检查：

• 确认tsconfig.json中isolatedModules为false（默认值），该选项会强制模块独立编译，可能影响类型合并。
• 避免将需要内联的接口标记为全局声明（如declare global），除非你确实需要全局类型。

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