如何为NPM包配置根目录index桶文件实现直接导入

• 已知barrel文件通过index.ts重新导出模块来组织导入，项目内部可直接通过目录名导入模块。现在发布NPM包时，希望使用者能从包根目录直接导入（如import { User, UserService, Loan, LoanService } from "package"），但当前构建产物都在dist目录，导致使用者需要从package/dist导入。
• 尝试在根目录index.ts中编写export * from "./dist"时，出现TS错误：TS2306: File 'D:/Temporary/test/dist/index.d.ts' is not a module.，需明确错误原因及解决办法。

目录结构 #

.
├── dist
│   ├── src
│   │   ├── loan
│   │   │   ├── index.d.ts
│   │   │   ├── index.js
│   │   │   ├── loan.model.d.ts
│   │   │   ├── loan.model.js
│   │   │   ├── loan.service.d.ts
│   │   │   └── loan.service.js
│   │   └── user
│   │       ├── index.d.ts
│   │       ├── index.js
│   │       ├── user.model.d.ts
│   │       ├── user.model.js
│   │       ├── user.service.d.ts
│   │       └── user.service.js
│   ├── index.d.ts
│   ├── index.js
│   └── index.js.map
├── node_modules
├── src
│   ├── loans
│   │   ├── index.ts
│   │   ├── loan.model.ts
│   │   └── loan.service.ts
│   └── user
│       ├── index.ts
│       ├── user.model.ts
│       └── user.service.ts
├── index.ts
├── package.json
├── package-lock.json
├── README.md
└── tsconfig.json

package.json #

{
  "name": "totally-unique-package-name",
  "version": "0.0.1",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "rimraf dist && tsc",
    "prepack": "npm run build"
  },
  "devDependencies": {
    "rimraf": "^3.0.2",
    "typescript": "^4.7.4"
  },
  "description": "description",
  "author": {
    "name": "name",
    "email": "email"
  }
}

tsconfig.json #

{
  "compilerOptions": {
    "module": "commonjs",
    "declaration": true,
    "removeComments": true,
    "target": "es2017",
    "baseUrl": "./",
    "skipLibCheck": true,
    "outDir": "./dist"
  }
}

npm publish --dry-run 输出 #

$ npm publish --dry-run
npm WARN config global `--global`, `--local` are deprecated. Use `--location=global` instead.

> totally-unique-package-name@0.0.1 prepack
> npm run build                            

npm WARN config global `--global`, `--local` are deprecated. Use `--location=global` instead.

> totally-unique-package-name@0.0.1 build
> rimraf dist && tsc                     

npm notice                                                        
npm notice package: totally-unique-package-name@0.0.1             
npm notice === Tarball Contents ===                               
npm notice 0B   README.md                                         
npm notice 148B dist/index.d.ts                                   
npm notice 688B dist/index.js                                     
npm notice 108B dist/src/loan/index.d.ts                          
npm notice 308B dist/src/loan/index.js                            
npm notice 65B  dist/src/loan/loan.model.d.ts                     
npm notice 121B dist/src/loan/loan.model.js                       
npm notice 78B  dist/src/loan/loan.service.d.ts                   
npm notice 242B dist/src/loan/loan.service.js                     
npm notice 108B dist/src/user/index.d.ts                          
npm notice 308B dist/src/user/index.js                            
npm notice 65B  dist/src/user/user.model.d.ts                     
npm notice 121B dist/src/user/user.model.js                       
npm notice 78B  dist/src/user/user.service.d.ts                   
npm notice 242B dist/src/user/user.service.js                     
npm notice 409B package.json                                      
npm notice === Tarball Details ===                                
npm notice name:          totally-unique-package-name             
npm notice version:       0.0.1                                   
npm notice filename:      totally-unique-package-name-0.0.1.tgz    
npm notice package size:  1.1 kB                                  
npm notice unpacked size: 3.1 kB                                  
npm notice shasum:        f1a8965180641151e0be6ee2d906615bef4154cc
npm notice integrity:     sha512-9v9wjvaxLH314[...]o6z5bYWckBpzA==
npm notice total files:   16                                      
npm notice                                                        
npm notice Publishing to https://registry.npmjs.org/ (dry-run)    
+ totally-unique-package-name@0.0.1 

1. 实现从包根直接导入的正确方式 #

你不需要手动复制dist文件到根目录，也不需要在根目录写指向dist的index.ts。当前你的package.json已经配置了main和types字段指向dist/index.js和dist/index.d.ts，这已经满足用户从包根导入的需求——使用者只需写import { ... } from "totally-unique-package-name"，Node.js和TypeScript会自动根据这两个字段找到对应文件，无需添加/dist后缀。

若使用者仍需要写/dist，大概率是其项目配置问题或你之前的版本未正确设置入口字段，可在README中明确告知用户直接从包名导入即可。

2. 解决export * from "./dist"的TS错误 #

出现TS2306错误的原因：

• 根目录的index.ts是源文件，你在其中导入dist目录的编译产物，而dist文件是编译后的JS/TS声明文件。TypeScript处理源文件时，若dist目录未生成（比如build前），或无法正确识别dist/index.d.ts为模块，就会报错。
• 根目录的index.ts会被TypeScript编译到dist目录（你的tsconfig未排除它），导致dist内出现重复逻辑，引发混乱。

正确做法：

• 删除根目录的index.ts，在src目录下创建总barrel文件src/index.ts，统一导出所有对外暴露的模块：

  // src/index.ts
  export * from './user';
  export * from './loans';
  

• 重新执行npm run build，dist目录会自动生成包含所有导出内容的index.js和index.d.ts。
• 保持package.json的main和types字段指向dist/index.js和dist/index.d.ts即可。

额外优化建议 #

• 在tsconfig.json中添加include和exclude字段，明确编译范围，避免编译无关文件：

  {
    "compilerOptions": {
      // 现有配置
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist"]
  }
  

• 确认package.json的files字段包含dist，确保发布时所有编译产物被打包（这一步你已完成）。

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