如何发布 TypeScript npm 包?
发布一个 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
。我们还需要声明那个文件要发布,如果我们使用了sourceMap
和declarationMap
,我们也需要上传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 一点不难,建议大家可以看下官方文档,这里也有几个步骤:
- 确定有
package.json
文件 - 构建项目(
npm run build
如果你用的是上面的例子) - 如果你还没有 npm 账号,需要认证(
npm login
) - 执行 npm publish 命令
注意:如果你要更新你的包,需要修改你的版本 version
参数在你上传之前。
还有更复杂的和更推荐的发布方式,比如使用 GitHub 的一些方式,特别是开源包,但这超出了本文的范围。
总结
通过这些方法,你的 TypeScript 包会提供更好的类型提示以及模块支持(ES/CommonJS),使你的包能够被更广泛的使用。
码云笔记 » 如何发布 TypeScript npm 包?
![](https://media.mybj123.com/wp-content/uploads/2024/02/1706962282-d2a91681b352c3a.png)