如何发布一个 TypeScript npm 包？

站长

2024年04月07日 18:19 · 阅读数 4

原文链接：blog.liblab.com/typescript-…

发布一个 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），使你的包能够被更广泛的使用。

侵权请联系，马上删除