使用 tsup 创建你的全新现代 TypeScript/JavaScript 库

原文链接：Create Your New Modern TypeScript/JavaScript Library With tsup，2022.11.15，by Christopher T.

导读：tsup 是基于 esbuild 开发的一个新型打包工具（比 rollup 还新）。内置了 TypeScript 支持，零配置、开箱即用，帮助你高效创建现代 TypeScript/JavaScript 库。

现在是作为开发者的最好的时候，尤其对 JavaScript 开发者来说。JavaScript 生态系统庞大而充满惊喜，开源项目不断演进，一个又一个创新工具涌现。有像 React 这样用于开发复杂的用户界面的库、像 Next 这样用于构建服务器端渲染应用程序的框架、像 Gatsby 这样用于构建静态网站的程序，还有 Lerna 和 Turborepo 这种构建多包仓库（monorepo）的工具等等。

提交错误修复或提出新想法的 Pull Request 通常是开发者参与开源项目时首先想到的。我们还可以选择开发自己的开源项目。如果你计划写自己的 JavaScript 开源库，本文就比较适合你。对于那些好奇但没有听说过 tsup（一款替代流行 rollup 的、现代的、强大且健壮的 JavaScript 工具） 的人来说，我们将介绍如何使用它创建自己的 JavaScript 库，并将其提交到 npm 中央仓库（npm registry）供其他人安装使用。我们的示例代码使用 TypeScript 编写（ TypeScript 是 JavaScript 的一个超集）。

tsup 由 esbuild 驱动。esbuild 是一个非常快速、现代化且无需缓存即可实现极速打包功能的 JavaScript 打包器 。esbuild 无需配置就能打包 TypeScript 库的工具，可以打包任何受到 Node.js 平台支持的文件，包括 .js、.json、.mjs、.ts、.tsx，在本文撰写时 esbuild 也实验性地支持 .css 文件的打包。

项目初始化

开始介绍前，请先启动一个终端并创建一个新目录（可以随意命名）。然后在终端中输入 cd 进入该目录。本文我们使用目录名 my-typescript-library。

mkdir my-typescript-library
cd my-typescript-library

我们需要一个 package.json 文件，所以在终端中输入 npm init -y。

npm init -y

这将立即使用默认设置为我们创建一个 package.json 文件。

创建一个名为 src 的目录，然后在该目录中创建一个名为 index.ts 的新文件。这个文件是我们库的入口点。

由于要使用 tsup，所以将它作为开发依赖安装：

npm i -D tsup

由于我们在 src/index.ts 中创建的文件将成为我们库的入口点，因此我们需要指示 tsup 消费这些文件并将其输出到某个位置（我们将设置输出目录为 ./dist）。

继续修改 package.json，在 scripts 属性下添加 build 和 start 脚本：

{
  "name": "my-typescript-library",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "tsup src/index.ts",
    "start": "npm run build -- --watch",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "Christopher Tran <pfftdammitchris@gmail.com>",
  "license": "MIT",
  "devDependencies": {
    "tsup": "^6.4.0"
  }
}

现在当我们运行 npm run build 时，tsup 编译器会使用 src/index.ts 并自动编译文件到 ./dist 目录中：

下面是目录结构：

默认情况下，tsup 将打包文件输出到 ./dist 目录，不过我们可以通过配置文件进行配置，这块我们后面会详细介绍。

如果我们查看生成的文件 ./dist/index.js，会发现内容为空。这是因为我们还没有为库编写任何代码。

添加功能代码

让我们输入一些基本代码，以便更详细地分析输出结果：

src/index.ts：

export function sayHello() {
  console.log('hello')
}

再次运行 npm run build，并注意 tsup 是如何将我们的代码转译为 ES5 的：

让我们通过创建一个名为 client.js 的文件来测试我们的库，包含以下代码：

const { sayHello } = require('./dist')

sayHello()
sayHello()
sayHello()
sayHello()
sayHello()

在终端中输入 node client.js 运行文件，你会看到：

很好！我们的库到目前运行得非常顺利。

自定义配置：通过 tsup.config.ts

当然我们还可以使用 tsup 做更多的事情——通过配置文件。tsup 在运行时会自动读取并名为 tsup.config.ts 的文件。我们创建一下这个文件，并添加以下内容：

import type { Options } from 'tsup'

const config: Options = {
  //
}

export default config

通过这个配置文件，我们可以指示 tsup 编译器执行不同的操作。

例如，我们可以通过将 dts 设置为 true 来指示 tsup 生成 TypeScript 声明文件：

const config: Options = {
  entry: ['src/index.ts'],
  dts: true,
}

对于这个设置，我们需要在项目中安装 TypeScript，否则会收到一个错误：

npm i --save-dev typescript

当我们再次运行 npm run build 时，tsup 就帮我们生成了一个额外的声明文件。

我们还可以生成源代码映射文件，以便在调试过程中生成更准确的堆栈跟踪（stack traces）信息：

const config: Options = {
  entry: ['src/index.ts'],
  dts: true,
  sourcemap: true,
}

现在，客户端代码（client.js）就能在 IDE（如 VS Code）中看到 TypeScript 类型提示了：

多格式输出

一个库的作者面临的问题是如何支持不同的客户端消费格式。目前有几种常见的格式：

格式	描述
iife	立即调用的函数表达式（适用于浏览器）
cjs	CommonJS
esm	ECMAScript 模块

tsup 中我们可以轻松地通过 format 字段配置，生成这三种格式。

const config: Options = {
  entry: ['src/index.ts'],
  dts: true,
  sourcemap: true,
  format: ['iife', 'cjs', 'esm'],
}

执行后的打印输出：

目录结构：

在我们的 client.js 文件中，目前我们可以没有问题地使用我们的库。然而，为了让消费者导入与其项目所使用格式相对应的文件，我们需要编辑 package.json 为特定导入方式指向特定格式的文件。

关于 exports 的工作原理，超出了本篇文章的范围，有兴趣的同学，可以点击这里转到官方的 Node.js 文档进行查看。

发布 npm 包

现在我们已经介绍了创建一个最小化的现代 JavaScript/TypeScript 库所需的基本推荐要求！下一步，我们需要将我们的包发布到 npm 中央仓库中，方便三方用户可以通过 npm 安装我们的包。

为此，在 package.json 中添加一个 publishConfig 键，并将 access 字段设置成“public”：

{
  "publishConfig": {
    "access": "public"
  }
}

在终端中输入 npm publish，你应该会看到类似于以下内容（将 my-typescript-library 替换成你的包名）：

结束！

本文对应的代码仓库，可以点击这里查看。

总结

这篇文章到此结束！希望对你有帮助，谢谢！