如何优雅的发布一个 TypeScript 软件包?

更新日期: 2024-02-20阅读: 516标签: 软件

npm 发布软件包本身并不是一个特别困难的挑战。但是,配置你的 TypeScript 项目以取得成功可能是一个挑战。你的软件包能在大多数项目上运行吗?用户能否使用类型提示和自动完成功能?它能与 ES Modules (ESM) 和 CommonJS (CJS) 风格的导入一起使用吗?

阅读完本篇文章后,你将了解如何使你的 TypeScript 包在任何(或大多数)JavaScript 和 TypeScript 项目中更易于访问和使用,包括浏览器支持!


创建 TypeScript 项目

如果你正在阅读本文,那么你很可能已经建立了一个 TypeScript 项目。如果这样做,你可能想跳到后续步骤或留下来检查是否存在差异。

让我们首先创建基本 Node.js 项目并添加 TypeScript 作为开发依赖项:

npm init -y
npm install typescript --save-dev

你可能希望在 src 文件夹中构建代码。因此,让我们在其中创建包的入口点:

mkdir src
touch src/index.ts

现在,Node.js 和浏览器不理解 TypeScript,因此我们需要设置 tsc (TypeScript 编译器)将 TypeScript 代码编译为 JavaScript。让我们通过运行以下命令将 tsconfig.json 文件添加到我们的项目中:

npx tsc --init

如果我们现在运行 npx tsc,它会扫描我们的文件夹并在与 .ts 文件相同的目录中创建 .js 文件(这是不可取的)。让我们在运行之前添加更好的配置,以免造成混乱。

将以下行添加到 tsconfig.json:

{
    "compilerOptions": {
        // ... Other options
        "rootDir": "./src", // Where to look for our code
        "outDir": "./dist", // Where to place the compiled JavaScript
}

我们还向 package.json 添加一个“build”脚本:

{
    "scripts": {
        "build": "tsc"
    }
}

如果我们现在运行 npm run build ,一个新的 dist 文件夹将出现,其中包含已编译的 JavaScript。如果你使用的是 Git,请确保将 dist 文件夹添加到 .gitignore 中。


设置 tsc 以获得最佳开发者体验

我们已经可以将 TypeScript 编译为 JavaScript。但是,如果你按原样将其发布到 npm,则只能在其他 JavaScript 项目中无缝使用它。此外,默认目标配置是“es2016”,而现代浏览器最多仅支持“es2015”。那么让我们解决这个问题吧!

首先,让我们将目标(target)更改为 es2015 (或 es6 ,因为它们是相同的)。 esModuleInterop 默认为 true。让我们保持原样,因为它通过允许 ESM 样式导入来提高兼容性。

我们使用 TypeScript 都有一个原因:类型!但是,如果你现在就构建并发布你的软件包,那么它将不会发布任何类型。让我们通过将 declaration 设置为 true 来解决这个问题。这将与 .js 文件一起生成声明文件(.d.ts)。仅凭这一点,你的软件包就能在 TypeScript 项目中使用,甚至在 JavaScript 项目中也能提供类型提示。

声明文件在改善支持和开发人员体验方面已经发挥了很大作用。然而,我们可以通过添加 declarationMap 来更进一步。这样,将生成源映射 (.d.ts.map),以将我们的声明文件 (.d.ts) 映射到我们的原始 TypeScript 源代码 (.ts)。这意味着代码编辑器在使用“转到定义”时可以转到原始 TypeScript 代码,而不是编译后的 JavaScript 文件。

当我们这样做时,sourceMap 将添加源映射文件 (.js.map),这些文件允许调试器和其他工具在实际处理发出的 JavaScript 文件时显示原始 TypeScript 源代码。

使用 declarationMap 或 sourceMap 意味着我们还需要将源代码与软件包一起发布到 npm。

综上所述,这是我们最终的 tsconfig.json 文件:

{
    "compilerOptions": {
        "target": "es2015",
        "module": "commonjs",
        "strict": true,
        "esModuleInterop": true,
        "rootDir": "./src",
        "outDir": "./dist",
        "sourceMap": true,
        "declaration": true,
        "declarationMap": true,
    }
}


package.json

这里的事情要简单得多。当用户导入包时,我们需要指定包的入口点。因此,让我们将 main 设置为 dist/index.js 。

除了入口点之外,我们还需要指定主要类型声明文件。在这种情况下,这将是 dist/index.d.ts 。

我们还需要指定随包一起提供哪些文件。当然,我们需要发送构建的 JavaScript 文件,但由于我们使用的是 sourceMap 和 declarationMap ,所以我们还需要发送 src 。

这是包含所有内容的参考 package.json :

{
  "name": "the-greatest-sdk", // Your package name
  "version": "1.0.3", // Your package version
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc"
  },
  "keywords": [], // Add related keywords
  "author": "liblab", // Add yourself here
  "license": "ISC",
  "files": ["dist", "src"],
  "devDependencies": {
    "ts-node": "^10.9.1",
    "typescript": "^5.0.4"
  }
}


发布到 NPM

发布到 NPM 并不困难。我强烈建议你查看官方说明,但以下是一般步骤:

  1. 确保你的 package.json 设置正确。
  2. 构建项目(如果你遵循指南,则使用 npm run build )。
  3. 如果你还没有登录,请使用 npm login 向 npm 进行身份验证(你需要一个 npm 帐户)。
  4. 运行 npm publish 。

请记住,如果你更新软件包,则需要在再次发布之前增加 package.json 中的 version 选项。

有更复杂的(和推荐的)方法来进行发布,例如使用 GitHub Action 和 releases,特别是对于开源包,但这超出了本文的范围。

翻译来自:https://blog.liblab.com/typescript-npm-packages-done-right/

链接: https://www.fly63.com/article/detial/12651

ManageEngine全球副总裁Sabhlok:通过简单易用的工具软件来优化IT 运维管理

人物简介:ManageEngine全球副总裁,获杜克大学福库商学院MBA学位。拥有超过20年的企业级软件行业经历,曾就职于Embarcadero、BMC等公司, 任技术、营销、销售与执行高级管理职位。十多年前,除了那些最大的公司外

时下流行的9种恶意软件,你都了解吗?

当今时代,网络世界处处充满了危机,对于网络用户来说,能够对各种类型的恶意软件进行了解,也许有助于在网上冲浪的过程中保全自身。病毒、蠕虫、木马、杂交程序和僵尸网络、勒索软件

软件开发行业应该有职业道德规范来约束吗?

在软件开发领域,经常会发生由于从业者的职业道德不到位而引发的事件,比如,InfoQ 过往就曾报道过离职程序员利用测试账户套现千万美元、华夏银行一位技术处长利用职务便利在华夏银行总行核心系统内植入计算机病毒程序

常用报表软件有哪些?

在企业管理过程中,报表往往都会通过一些简洁的图表方式,为大家呈现所有的数据。报表软件,可以在操作的过程中有效提升工作效率,所以有很多企业早就已经选择跟随信息技术的潮流,选择报表软件工具。

如何打造一款好软件?

糟糕的软件是世界上为数不多的无法用金钱解决的问题之一。数十亿美元的航空公司拥有的航班搜索应用程序往往不如学生群体开发的那些应用程序好用。尽管面临着拼车服务的威胁,世界各地的老牌出租车公司还在使用糟糕

如何在软件开发行业选择一条正确的职业道路?

当我进入软件开发领域时,我非常兴奋。我想要同时学习所有东西:游戏开发、移动开发、人工智能以及所有与之相关的内容。我把时间浪费在了写“hello world”和一些简单的程序上,使用了大约 30 种语言,只是为了弄清楚我应该学哪一种

如何应对软件复杂度

至今也写了四年多代码,但如何在功能不断增多的同时写出可读、可维护、可扩展的或者说优雅的代码一直令我感到非常困惑。最近读了《Clean Architecture》以及 Domain Driven Design(简称 DDD) 相关软件架构的书,对这个问题有了进一步的思考。

软件的复杂性正在杀死我们

现在有一个常见现象:企业想要更快更便宜地构建软件。这当然是一个可以理解和值得称赞的目标。且每个工程师都应该全心全意支持这个目标。

软件开发的七条原则

软件系统存在的原因:为用户提供价值。所有的决定都应该考虑到这一点。在指定系统需求之前,在关注系统的各个功能之前,在确定硬件平台或开发过程之前,问问自己以下问题:这是否能为系统真正增加价值?

关于软件开发你真正需要知道的几个事情

我之所以写这篇文章是因为有一个朋友最近决定跻身软件工程行业。我的这位朋友聪明,精力充沛,品貌兼优,又善于学习:每个人都认为这样的人才必将有一番作为。但是,在踏出第一步时,他依然有很多东西需要学习。

点击更多...

内容以共享、参考、研究为目的,不存在任何商业目的。其版权属原作者所有,如有侵权或违规,请与小编联系!情况属实本人将予以删除!