为基于打字稿的库在 package.json 类型字段中放置啥

Posted 2023-03-13

【中文标题】为基于打字稿的库在 package.json 类型字段中放置啥

【英文标题】：What to put in package.json types field for typescript based libs为基于打字稿的库在 package.json 类型字段中放置什么

【发布时间】：2018-08-03 18:33:24

【问题描述】：

我有点困惑如何最好地开发多个打字稿模块与代码导航并行并仍然以正确的方式发布。那么我应该在 package.json “types” 字段中真正放入什么？

根据：Typescriptlang.org/publishing.html

我应该像这样引用我生成的index.d.ts：

    "name": "awesome",
    "author": "Vandelay Industries",
    "version": "1.0.0",
    "main": "./lib/main.js",
    "types": "./lib/main.d.ts"

如果我随后使用 npm link 并行开发一个依赖于这个模块的模块，例如 vscode 中的代码导航让我直接跳到这个定义文件中。这不是我想要的。

我想进入源文件以便能够在 dep 中并行编辑。没有带有源映射的 tsconfig 设置，内联或没有在这方面有所帮助。我可能在这里遗漏了一些东西。我管理工作流程以正常工作的唯一方法是实际指向源 main.ts 文件：

    "name": "awesome",
    "author": "Vandelay Industries",
    "version": "1.0.0",
    "main": "./lib/main.js",
    "types": "./src/main.ts"

但是，这会在发布时破坏，对吗？

至少如果我将 src 放在 .npmignore 下。我无法理解拥有多个打字稿模块的良好工作流程的最佳方式。

我的意思是，我不想在发布过程中破坏 package.json ......？

【问题讨论】：

这应该在 vscode 和所有其他应该使用 TypeScript 的 IDE 中修复（WebStorm 代码导航的行为方式相同）。理想情况下，“转到定义”应该检查d.ts 文件是否在node_modules 下的符号链接目录中，然后找到实际的源目录并以某种方式找到生成.d.ts 的.ts 文件。

@artem 如果启用了sourcemap，那么为什么不启用tsconfig.json中的sourcemap呢？

@Yu sourcemaps 用于将生成的 javascript 代码中的位置映射到源文件中的位置。这个问题是关于从源文件中的符号位置到另一个打字稿源文件中定义符号的位置。我不确定源地图在这里有什么帮助。

在 TypeScript 2.9 中有一个新选项 --declarationMap 将生成一个额外的 .d.ts.map 映射从 .d.ts 到 .ts，但我怀疑你需要在监视模式下运行以保持.d.ts.map 是最新的。

你找到解决这个问题的方法了吗？

【参考方案1】：

TypeScript 项目参考

据我所知，TypeScript Project References 将满足您的要求：

VS Code 导航转到*.ts 源文件而不是*.d.ts 文件。 package.json types 值引用*.d.ts 文件。

在不改变发布方式/发布内容的情况下提供开发人员工具。

演示

我创建了一个简单的demo project in GitHub。以下是如何使用代码导航设置项目引用的要点。

package01

tsconfig.json 允许另一个 TypeScript 项目引用它 (composite) 和代码导航工作 (declarationMap)。在 package.json 中，NPM 范围（@shaunluttin）并不是完全必要的；我将其包括在内以避免命名冲突。

tsconfig.json

  "compilerOptions": 
    "target": "es5",
    "composite": true,
    "declarationMap": true
  

package.json

  "name": "@shaunluttin/package01",
  "version": "1.0.0",
  "main": "index.js",
  "types": "index.d.ts"

package02

tsconfig.json references package01。这就是设置工具的原因。 package.json 以与通常相同的方式依赖于 package01。

tsconfig.json

  "compilerOptions": 
    "target": "es5"
  ,
  "references": [
    
      "path": "../package01"
    
  ]

package.json

  "name": "@shaunluttin/package02",
  "version": "1.0.0",
  "main": "index.js",
  "types": "index.d.ts",
  "dependencies": 
    "@shaunluttin/package01": "1.0.0"
  

NPM 链接

对于本地开发，这两个包是connected with npm link。

cd package01
npm link

cd ../package01
npm link @shaunluttin/package01

最后的想法

The documentation 提到了一些过于复杂的警告，无法在此答案中列出。

【讨论】：

在“NPM 链接”下放置“cd ../package01”的意思是“cd ../package02”吗？

【参考方案2】：

这是一种重量较轻的替代方案，但需要使用 PNPM。在您的 package02 中将其添加到您的 package.json：

"type": "module",
"exports": 
    ".": "./src/index.ts"
  ,
  "types": "./src/index.ts",
  "publishConfig": 
    "exports": 
      ".": "./lib/index.js"
    ,
    "types": "./lib/index.d.ts"
  ,

当您的包发布时，publishConfig 选项将覆盖 src 中的开发引用。 注意，我正在用这个解决方案构建一个 ESM 包。不确定 CJS。