Skip to content

Latest commit

 

History

History
136 lines (122 loc) · 7.44 KB

publish-npm-package-using-typescript.md

File metadata and controls

136 lines (122 loc) · 7.44 KB
Raw

#! https://zhuanlan.zhihu.com/p/404682867

使用TypeScript发布NPM包（2021年版）

本文受篇幅限制，很多东西无法讲得特别细致，详细信息可以查看文中链接。本文原始Markdown文本保存在GitHub。

步骤1：在GitHub上创建一个新的项目

  • 添加READMD
  • 添加.gitignore，类型选择node
  • 添加一个合适的开源license
  • Clone仓库到本地

步骤2：添加TypeScript和ESLint支持

本小节的很多步骤参考自Getting Started - Linting your TypeScript Codebase。

注意TSLint已经过时，不推荐使用，请使用ESLint。

  • npm i -D typescript
    • -D表示开发环境的依赖。由于最终发布到npm的包只包含JavaScript，所以使用这个包的用户不需要TypeScript。
    • 同时也不建议将TypeScript全局安装，否则其他的开发者可能使用一个不同版本的TypeScript，这可能会导致问题。
  • npm i -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
    • 显然和Lint相关的东西都只在开发环境中使用。
  • 在根目录添加一个名为.eslintrc.js的文件，其内容如下： 
    module.exports = {
    root: true,
    parser: '@typescript-eslint/parser',
    plugins: [
        '@typescript-eslint',
    ],
    extends: [
        'eslint:recommended',
        'plugin:@typescript-eslint/recommended',
        "plugin:node/recommended",
        "prettier",
    ],
};
    • 默认ESLint会解析JavaScript代码，但是不解析TypeScript代码。所以我们通过parser: '@typescript-eslint/parser'来指定使用TypeScript的解析器。
    • plugins: ['@typescript-eslint']表示使用TypeScript的插件（即上面安装的@typescript-eslint/eslint-plugin）。
    • extends: [ ... ]声明使用的扩展
      • eslint:recommended表示使用ESLint的建议规则
      • plugin:@typescript-eslint/recommended表示使用TypeScript的建议规则
      • 另外两个下面再讲
  • npm i -D eslint-plugin-node
    • 给ESLint添加Node.js相关的规则
    • .eslintrc.js中的"plugin:node/recommended"表示使用这里推荐的规则
  • 在根目录添加一个名为.eslintignore的文件，此文件告诉ESLint不用lint这些文件夹里的文件。其内容如下： 
    # don't ever lint node_modules
node_modules
# don't lint build output (make sure it's set to your correct build folder name)
lib
    • node_modules是依赖包的文件夹，所以不需要lint。
    • lib是存放构建文件的输出文件夹，所以不需要lint。注：lib这个名字只是我个人的选择，你也可以选择其它文件夹作为输出文件夹。常见的名字包括：dist, build, out, release等等。
  • node ./node_modules/typescript/bin/tsc --init：初始化TypeScript配置文件tsconfig.json，修改以下配置：
    • "declaration": true：让tsc自动生成对用的.d.ts文件。
    • "outDir": "./lib"：指定输出文件夹，和上面说的lib一致。
    • "include": ["src"]：按照我的个人习惯，源代码文件（除了测试文件）都放在src文件夹里。注意：include配置和compilerOptions配置是同一个级别的，不像上面两个是从属关系。
  • 在package.json中的scripts配置中添加"build": "tsc"，以后就可以通过执行npm run build来使用TypeScript编译工程到lib文件夹。

步骤3：使用jest作为测试框架

  • npm i -D jest @types/jest ts-jest
    • 与测试相关的包显然也只在开发环境中使用。
    • 同样，我们通过ts-jest包来让Jest支持TypeScript代码。
  • npx ts-jest config:init：初始化Jest配置文件jest.config.js，并修改，我的配置如下： 
    /** @type {import('ts-jest/dist/types').InitialOptionsTsJest} */
module.exports = {
    preset: 'ts-jest',
    testEnvironment: 'node',

    "transform": {
        "^.+\\.(ts|tsx)$": "ts-jest"
    },
};
    • preset: 'ts-jest'：使用ts-jest的预设配置
    • testEnvironment: 'node'：使用Node.js作为测试环境
    • "transform": {}：告诉Jest哪些代码需要使用ts-jest来转换
    • 其它配置请参考Jest配置文件。
  • 在package.json中的scripts配置中添加"test": "jest"，以后就可以通过命令npm t来执行测试。
  • 编写测试文件
    • Jest默认会执行__tests__文件夹下的TypeScript文件，所以我们将测试代码放在__tests__文件夹下。
    • 由于上面我们在tsconfig.json中配置了"include": ["src"]，所以测试文件不会被编译，最终的npm包中也不会有测试文件。

步骤4：使用prettier来格式化代码

  • npm i -D prettier
  • echo {}> .prettierrc.json告诉编辑器等工具你要使用的格式化工具是prettier。
  • 新建一个.prettierignore文件，内容如下（请根据自己的情况自行增删）： 
    # Ignore artifacts:
node_modules
lib
coverage
  • npm i -D eslint-config-prettier：安装eslint-config-prettier，这个包是用来让eslint支持prettier的。 并修改.eslintrc.js：回顾前文，我们在extends中添加的"prettier"。
    • 注意，"prettier"一定要放在extends的最后一个
    • 由于ESLint的规则和Prettier的规则略有细微差别，所以我们需要eslint-config-prettier提供的规则来extends ESLint的规则。

如果你使用VS Code，下面的步骤可以使其支持prettier的格式化：

  • 安装Prettier - Code formatter扩展
  • 打开VS Code的设置（Ctrl-Shift-P -> references: Open Workspace Settings (JSON)），将以下配置添加到其中： 
    {
    "editor.defaultFormatter": null,
    "[javascript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[typescript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[jsonc]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "editor.formatOnType": true,
    "editor.formatOnSave": true,
}
    • "esbenp.prettier-vscode"：即上面扩展提供的Prettier格式化器
    • 上面配置了JavaScript，TypeScript和JSON在修改和保存时都会自动格式化。参考官方文档修改上面配置来满足你自己的需求。

步骤5：实现你的库的功能

用你的库实现任何你想要的功能

步骤6：发布到npm

  • 注册npm账号
  • npm adduser：添加npm账号到本机
  • npm run build：打包你的库
  • npm publish：发布到npm

步骤7：最后别忘了给本文点赞。

  • 请追更本文，因为前端发展很快，所以我在必要时会更新文章。
  • 本文是我写Markdown-It Plugin for Zhihu CommonMark时的记录，上面有什么我讲得不明白的，可以参考。