如何发布 TypeScript npm 包?

目录
文章目录隐藏
  1. 创建一个 TypeScript 项目
  2. 最佳实践
  3. package.json
  4. 发布到 npm
  5. 总结

发布一个 npm 包不难,成功配置你的 TypeScript 项目才难。你的包能够适配大多数项目嘛?有输入提示和自动补全嘛?能够支持 ES 模块和 CommonJs 模块导入嘛?

在读了这篇文章之后,你会理解如何去让你的 TypeScript 在任何(大多数) JavaScript 和 TypeScript 项目中更适用,包括浏览器环境。

创建一个 TypeScript 项目

如果你已经创建了一个 TypeScript 项目,你可以跳过这个步骤或者对比一下不同点。

让我们创建一个 Node.js 项目并添加 TypeScript 依赖:

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

创建一个入口文件:

mkdir src
touch src/index.ts

目前 Node.js 和浏览器原生都不支持 TypeScript,所以我们需要用 tsc(TypeScript 编译器)去编译我们的 TS 代码,并生成 JS 代码。

添加tsconfig.json文件到我们项目中:

npx tsc --init

如果你现在使用npx tsc,它会在.ts文件的同级目录下生成一份编译过得.js文件(不期望这样)。让我们做一些配置,让它生成的更好。

添加下面几行到 tsconfig.json 中:

{
    "compilerOptions": {  
    // ... 其他参数
    "rootDir": "./src", // 在哪里找我们的代码
    "outDir": "./dist", // 把编译好的 js 放在那里
}

添加一个build脚本在package.json中:

{
    "script":{
        "build": "tsc"
    }
}

现在执行npm run build , 会生成dist目录,里面包含了编译好的.js文件。如果你使用了 Git,记得把你的dist添加到 .gitignore

最佳实践

我们现在把我们的 TS 编译成了 JS,如果你发布到 npm 上,这个包只能使用在一些 JS 项目中使用。还有一个问题是默认的 target 配置是 “es2016″,但是现代浏览器只支持到 “es2015″。让我们来修改一下配置。

首先,我们修改target为 “es2015″。 esModuleInterop 默认是 true。我们保留它以便于适配 ES 模块方式的引入。

我们使用 TypeScript 的主要原因就是类型支持!但是以我们现在的构建,目前还不支持。设置 declaration 为 true。它会生成声明文件 .d.ts.js 文件旁边。凭借这一点,你的包可以在 TS 项目中使用,并且还有类型提示。

我们还可以添加 declarationMap 这个会生成源映射(.d.ts.map)文件,在类型文件(.d.ts)和 TS 源码之间产生映射关系。这意味着我们在代码编辑器中可以直接使用 “Go To definition” 去到 TS 源码而不是编译后的 JS 文件。

与此同时,sourceMap 会帮我们添加 sourceMap 文件(.js.map), 这个文件会帮助我们在工具调试的时候映射 JS 到 TS 对应的源码。

使用 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。我们还需要声明那个文件要发布,如果我们使用了sourceMapdeclarationMap,我们也需要上传src

最终的package.json文件:

{
    "name": "the-greatest-sdk", // 包名
    "version": "1.0.3", // 包版本
    "main": "dist/index.js",
    "types": "dist/index.d.ts",
    "scripts": {
        "build": "tsc"
    },
    "keywords": [], 
    "author": "", 
    "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 账号,需要认证(npm login
  4. 执行 npm publish 命令

注意:如果你要更新你的包,需要修改你的版本 version 参数在你上传之前。

还有更复杂的和更推荐的发布方式,比如使用 GitHub 的一些方式,特别是开源包,但这超出了本文的范围。

总结

通过这些方法,你的 TypeScript 包会提供更好的类型提示以及模块支持(ES/CommonJS),使你的包能够被更广泛的使用。

「点点赞赏,手留余香」

1

给作者打赏,鼓励TA抓紧创作!

微信微信 支付宝支付宝

还没有人赞赏,快来当第一个赞赏的人吧!

声明:本站所有文章,如无特殊说明或标注,均为本站原创发布。任何个人或组织,在未征得本站同意时,禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益,可联系我们进行处理。
码云笔记 » 如何发布 TypeScript npm 包?

发表回复