开发npm第三方库的实战经验

Posted 2023-02-05 薛瑄

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了开发npm第三方库的实战经验相关的知识，希望对你有一定的参考价值。

最近在做一个第三方npm库，在本地调试，打包，发布阶段，深入了解了一下，不少参数的配置、工具的使用，这里总结记录一下

文章目录

一、编译
- 编译TypeScript
- webpack
二、指定包文件
- 黑名单：
- 白名单：
三、调试
四、发布npm包
- 为发布过程添加scripts

一、编译

这一步是为提供不同的使用方式，例如：ts写的代码，发布后可供ts和js使用，或者通过标签<script src="..."></script>引入

编译TypeScript

使用 tsc CLI 工具，我们可以将一个TypeScript文件编译成某一个指定版本的ECMA Script文件。

javascript这种无类型语言，最容易产生bug，所以TypeScript诞生了。浏览器引擎和Node.js都能够直接运行JavaScript，但无法直接运行TypeScript。于是就有了tsc命令行，用于把TypeScript编译为JavaScript（准确来说是ECSA Script，不过不同的环境对ECMA的各个版本兼容性又不太一样，往往还需要借助某些工具如babel 进一步编译成兼容各种浏览器环境的代码）

可以通过 tsc 命令直接传入参数，也可以通过 tsconfig.json来设置参数

tsconfig.json 配置


  "compilerOptions": 
    "target": "es5",
    "module": "commonjs",
    "declaration": true,
    "outDir": "./lib",
    "strict": true，

  ,
  "include": ["src"],
  "exclude": ["node_modules", "**/__tests__/*"]

target：编译之后生成的 JavaScript 文件需要遵循的标准，可选值：“ES3”（默认），“ES5”，“ES6”/“ES2015”，“ES2016”，“ES2017"或"ESNext”。我们选择了 es5 为了使包具有更好的浏览器兼容性。
module：指定生成哪个模块系统代码，默认值：target === “ES3” or “ES5” ? “CommonJS” : “ES6”。
declaration：是否生成对应的声明文件，默认值：false。在构建包时，应该设置为 true，这样 TypeScript 会将生成的声明文件和对应编译后的 JavaScript 代码一起导出，以便包可以在 TypeScript 和 JavaScript 项目中同时使用。本项目中生成的声明文件是 /lib/index.d.ts。
outDir：指定输出目录。编译后的 JavaScript 代码会在与 tsconfig.json 同级的 lib 文件夹中。
strict：是否启用所有严格类型检查选项，默认值：false。
include：指定要编译的目录。
exclude：指定不编译的目录。node_modules 和 tests 只是在开发阶段使用，构建阶段无需编译。

更多编译选项，看这里

tsc编译出来的只是代码，一个完整的npm，必须在根目录下包含package.json（这会在npm publish时，自动加入到生成的npm包中）

webpack

想通过标签引入的话，可使用webpack 打包为一个js文件

后续上传到仓库时，只需上传生成目录里的文件就可以了。那么该如何指定只上传该目录的文件呢？或者是React-Native项目，还有android 、ios的文件也要上传呢？接着来看，指定上传的包文件

二、指定包文件

在 .gitignore 中，我们添加 /lib 是因为不想 Git 远程仓库中有编译后的文件，但对于要发布的包则恰恰相反，我们不要源代码，只需要编译后的文件！有两种方式可以实现：

黑名单：

新建一个 .npmignore 文件，在其中添加不要的文件（夹），如果没有.npmignore，将会用.gitignore来代替

src
tsconfig.json
tslint.json
.prettierrc

这并不是一个好的实践，因为根目录下每次新增加一个文件（夹）都需要添加到 .npmignore 中，很容易忘记添加，导致敏感文件被打包发布，于是有了下面这种方式。

白名单：

在 package.json 中设置一个要发布的文件（夹）白名单"files": [“lib/**/*”]
只有 lib 文件夹会出现在发布的包里（README.md 和 package.json 会被默认添加）。

更多关于黑名单 VS 白名单的内容可以参考 blog.npmjs.org/post/165769…

如果是RN项目，就指定Android、iOS的目录到 package.json 的files中，像这样react-native-screens 的package.json

如果想像 react-navigation 在同一个工程下，对多个三方库进行发布管理，可以使用Lerna

三、调试

关于如何在本地的主工程引用调试第三方库，有三种方式，建议使用第三种：

1、link

网上很多文章介绍的是npm link，但是它会有很多问题。建议使用npx link

npx link <package-path>

2、在package.json 中使用本地路径

  "dependencies": 
    "bar": "file:../foo/bar"

3、使用yalc

使用上面两种方式，需要你手动去指定打包好的路径。yalc 的方案是在本地模拟一个 npm 仓库，把三方库发布到 .yalc目录下，真实发包无异。

安装

 npm install yalc -g   // 全局安装

使用

 //在第三库工程的根目录下执行 。重新发布也是执行该命令
 //把三方库发布到 .yalc目录下
 yalc publish  
 // 在主工程的根目录下执行， my_library 是三方库工程的名称（package.json name的值）
 // 在主工程的package.json 中可以看到，是引用了本地 .yalc 目录的三方库
 yalc add my_library

移除依赖

 yalc remove [my-package]  // 具体的某一个包 
 yalc remove --all // 移除所有依赖并还原

查看仓库信息

 yalc installations show

四、发布npm包

先在https://www.npmjs.com/ 注册账号

npm login # 登陆

npm publish # 发布

如果是发布到其他的仓库，可以在package.json中配置publishConfig ，它与命令行中 config 选项的参数是一样的

"publishConfig": 
      //默认是 https://registry.npmjs.org/
    "registry": "https://registry.xxxxx.com/"

为发布过程添加scripts

npm publish 会触发一些 scripts ，我们可以在发布前后，做一些代码检查，格式化等。往往我们每次发版也需要更新版本，提交代码等，也可以通过npm version 来让这些步骤自动执行。如下：

"scripts": 
  //npm version 命令 依次触发的三个脚本，
  "preversion": "npm run test",
  "version": "npm run format && git add -A src",
  "postversion": "git push && git push --tags"