发布的gRPC客户端npm包在NextJS中报错，求正确TS编译发布方法

我正在开发第一个npm包，是用于和gRPC服务器交互的TypeScript接口。发布后在Next.js项目里引入时出现大量错误，推测问题出在库的编译环节。

我的配置文件 #

tsconfig.json #

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2017",
    "declaration": true,
    "outDir": "./dist",
    "esModuleInterop": true
  },
  "include": ["./src/**/*"]
}

package.json #

{
  "name": "@company/grpc-client-js",
  "version": "0.1.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": [
    "./dist/",
    "./libraries/",
    "./node_modules/"
  ],
  "devDependencies": {
    "@babel/core": "^7.21.0",
    "@babel/preset-env": "^7.20.2",
    "@babel/preset-typescript": "^7.21.0",
    "@grpc/grpc-js": "^1.8.0",
    "@grpc/proto-loader": "^0.7.4",
    "@jest/test-sequencer": "^29.5.0",
    "@types/jest": "^29.4.0",
    "babel-jest": "^29.4.3",
    "grpc-tools": "^1.12.4",
    "jest": "^29.4.3",
    "ts-jest": "^29.0.5",
    "ts-node": "^10.9.1",
    "ts-protoc-gen": "^0.15.0",
    "typescript": "^4.9.4"
  },
  "dependencies": {
    "dotenv": "^16.0.3",
    "sha.js": "^2.4.11"
  }
}

安装方式 #

yarn add @company/grpc-client-js

报错信息 #

Module not found: Can't resolve 'fs'

我试过添加fallback解决了这个错误，但又出现更多需要添加fallback的错误。这只是临时方案，想请教如何正确编译并发布这个TypeScript项目，让它能在主项目里正常使用。

1. 修正package.json的files配置 #

files字段里包含./node_modules/是错误的——npm包发布时不能上传node_modules目录，会导致包体积臃肿且引入冗余依赖，直接删除该条目：

"files": [
  "./dist/",
  "./libraries/"
]

2. 调整TypeScript编译配置适配多环境 #

Next.js同时涉及浏览器和Node.js环境，当前编译成单一CommonJS模块无法适配。修改tsconfig.json，同时输出ES模块和CommonJS模块：

主tsconfig.json

{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ES2020",
    "declaration": true,
    "outDir": "./dist/esm",
    "esModuleInterop": true,
    "moduleResolution": "NodeNext"
  },
  "include": ["./src/**/*"]
}

新建tsconfig.cjs.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "CommonJS",
    "outDir": "./dist/cjs"
  }
}

然后在package.json中添加多入口配置，让环境自动匹配合适的模块：

"main": "./dist/cjs/index.js",
"module": "./dist/esm/index.js",
"types": "./dist/esm/index.d.ts",
"exports": {
  ".": {
    "import": "./dist/esm/index.js",
    "require": "./dist/cjs/index.js"
  }
}

3. 处理gRPC的环境兼容性问题 #

@grpc/grpc-js是Node.js专属库，无法在浏览器环境运行，有两种解决思路：

• 仅在Next.js API路由中使用：API路由运行在Node.js环境，不会出现模块缺失问题，客户端通过调用API接口间接和gRPC服务器交互。
• 改用gRPC-Web：如果必须在浏览器端直接调用，替换为@grpc/web库，并在服务端配置gRPC-Web代理，同时修改你的npm包基于gRPC-Web实现。

4. 修正依赖声明 #

将@grpc/grpc-js、@grpc/proto-loader从devDependencies移到dependencies——这些是包运行时必需的依赖，不是仅开发阶段使用：

"dependencies": {
  "@grpc/grpc-js": "^1.8.0",
  "@grpc/proto-loader": "^0.7.4",
  "dotenv": "^16.0.3",
  "sha.js": "^2.4.11"
}

5. 正确的编译发布流程 #

1. 清理旧编译产物：rm -rf dist
2. 编译ES模块：tsc
3. 编译CommonJS模块：tsc -p tsconfig.cjs.json
4. 本地测试：执行npm pack生成本地包，在Next.js项目中用yarn add ../path/to/your-package.tgz验证功能
5. 确认无误后发布：npm publish

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