typescript - 如何使用通用实用程序构建 NPM 包

Question

我需要为我们公司各种前端项目使用的一些常用功能制作一个 NPM 包，但非常不确定如何正确执行。我们正在使用 Typescript 和 tsdx似乎处理了几件我非常不确定如何正确做的事情，但它没有说明如何构建“实用程序”类型的包。

我不明白的是，应该 "main" 在 package.json指向，当一个包中没有一个合乎逻辑的单一导出/类/函数时？

它应该只导出整个包中的每一个“公共(public)”函数吗？如果是这样，这将如何影响摇树(我目前不太了解)和类似的事情？

如果不应该，应该"main"指向，又应该如何导出和导入东西？例如，我希望能够 import foobar from '@org/common/category/foobar ，但是 npm 创建包的方式，似乎打包的路径通常会包含 dist或 lib或类似的东西，我真的不想要。

一个人应该如何构建一个“多功能 NPM 包”来获得干净的导入和工作的 tree-shaking 和其他好东西？

有没有人在 GitHub 或其他可用的地方有任何好的、干净、简单的库示例？我曾尝试查看像 lodash 这样的项目，但它们通常不是用 Typescript 编写的，而且通常似乎有相当复杂的设置，包括 mono-repos、工作区、自定义构建脚本等......

Answer 1

How should one structure a "multi-function NPM package" to get both clean imports and working tree-shaking and other good things?

发布现代 es 模块

对于现代库(节点和浏览器)，您应该在 typescript 中编写源代码，并提供 es-module 分发

这个策略遵循新库应该是现代、精简和简约的理念——你的库应该只是一个公开可用的 es 模块目录

你的 package.json 应该包括

"type": "module",
"main": "dist/main.js",
"module": "dist/main.js",
"files": [
  "dist",
  "source"
],
"scripts": {
  "prepare": "tsc",
  "watch": "tsc -w",
},
"devDependencies": {
  "typescript": "typescript": "^3.8.3"
},

也许你的 tsconfig.json 有这样的条目

"baseUrl": ".",
"rootDir": "source",
"outDir": "dist",
"target": "esnext",
"lib": ["esnext", "dom"],
"module": "esnext",
"experimentalDecorators": true,
"sourceMap": true,
"declaration": true,

所有优化问题——即:捆绑、缩小、摇树、编译、polyfilling等——所有这些问题都已由消费者应用程序处理(如果库提供这些问题，那就是多余的膨胀)

遗留的 common-js 应用程序可以轻松地使用 esm 适配器来使用 es 模块分发

如果你绝对必须(请另外考虑)，你可以让你的双 esm+cjs 混合包:只需运行一个并行构建步骤 tsc -- --module=commonjs --outDir dist-cjs然后设置 package.json "main": "dist-cjs/main.js",你可以同时支持 commonjs 和 esm

具体答案

I need to make an NPM package for some common functionality used by various frontend-projects in our company, but very unsure how to do it properly. We're using Typescript, and tsdx seem to handle several things I'm very unsure how to do properly, but it doesn't say anything about how to structure a "utilities" type package.

这就是我推荐 esm 策略的原因:它适用于同构代码，也就是说，该库可以在前端项目和后端节点项目上无缝运行

What I don't understand is, what should "main" in package.json point to, when there's not a logical single export/class/function that makes sense in a package?

包.json "main"和 "module"字段是可选的——跳过它

我认为这是一个最佳实践:不要将单个入口点指定为您的“主要”——相反，您应该鼓励消费者明确选择他们想要的模块
import {makeLogger} from "authoritarian/dist/toolbox/logger/make-logger.js"
像上面这样的显式导入比重新导出可能未使用的模块的大树的索引要好，最好只导入你需要的东西来避免需要摇树

Should it just export every single "public" function in the whole package? And if so, how would that affect tree-shaking (which I currently don't understand super well) and things like that?

你只想设置你的 package.json "files"告诉 npm 发布 "dist" 的数组充满 es-modules 的目录——同时发布 "source"以便消费者在调试库中的任何内容时获得良好的 sourcemap 体验

鼓励用户直接导入模块消除了树抖动问题——因为你没有使用索引文件来聚合可能不需要的模块，你不必将它们摇出来——无论如何，处理包使用胖索引模块

[...] it seems the packaged path will often end up including dist or lib or something like that, which I really don't want.

是的，这曾经在美学上也困扰着我，但我克服了它

现在我喜欢它，包很简单，从根开始，和 dist 之间有区别和 source (比如访问源映射进行调试等)所以区别是公平的游戏

How should one structure a "multi-function NPM package" to get both clean imports and working tree-shaking and other good things?

我认为这个答案的策略将提供您正在寻找的东西

And does anyone have any good, clean, simple examples of libraries like these on GitHub or other available places? I have tried to look at projects like lodash, but they are often not written Typescript, and often seem to have rather complicated setups with mono-repos, workspaces, custom build scripts, etc...

我还没有制作流行的包(还没有，muahaha!)但是我的图书馆 authoritarian走着走..我最近制作了很多图书馆，我所宣讲的上述原则是我认为我学到的: renraku是我的同构 json-rpc 库， metalshop是我的 Web 组件库， shopper是我的 shopify 购物车 ui

其他不是我制作的非常好的库包括 lit-element .. 大多数库都不是新的，并且在 commonjs 世界中半途而废