On this page

On this page

TypeScript、Rollup 搭建工具库

Dec 31, 2019

前景提要

公司内总是有许多通用的工具方法、业务功能，我们可以搭建一个工具库来给各个项目使用。

要实现的需求：🤔

支持编辑器的快速补全和提示
自动化构建
支持自动生成 changlog
代码通过 lint 和测试后才能提交、发布

涉及的库

eslint + @typescript-eslint/parser
rollup
jest
@microsoft/api-extractor
gulp

初始化项目

新建一个项目目录如 fly-helper , 并 npm init 初始化项目。

安装 TypeScript

yarn add -D typescript

创建 src 目录，入口文件，以及 ts 的配置文件

fly-helper
 |
 |- src
 	 |- index.ts
 |- tsconfig.json

配置 tsconfig.json

/*  tsconfig.json */
{
  "compilerOptions": {
    /* 基础配置 */
    "target": "esnext",
    "lib": ["dom", "esnext"],
    "removeComments": false,
    "declaration": true,
    "sourceMap": true,

    /* 强类型检查配置 */
    "strict": true,
    "noImplicitAny": false,

    /* 模块分析配置 */
    "baseUrl": ".",
    "outDir": "./lib",
    "esModuleInterop": true,
    "moduleResolution": "node",
    "resolveJsonModule": true
  },
  "include": ["src"]
}

0

0

0

3

8

8

yarn add -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

fly-helper
 |- .eslintignore
 |- .eslintrc.js
 |- tsconfig.eslint.json

Parsing error: "parserOptions.project" has been set for @typescript-eslint/parser.
The file does not match your project config: config.ts.
The file must be included in at least one of the projects provided.eslint

/* tsconfig.eslint.json */
{
  "compilerOptions": {
    "baseUrl": ".",
    "resolveJsonModule": true
  },
  "include": ["**/*.ts", "**/*.js"]
}

// .eslintrc.js
const eslintrc = {
  parser: '@typescript-eslint/parser', // 使用 ts 解析器
  extends: [
    'eslint:recommended', // eslint 推荐规则
    'plugin:@typescript-eslint/recommended', // ts 推荐规则
  ],
  plugins: ['@typescript-eslint'],
  env: {
    browser: true,
    node: true,
    es6: true,
  },
  parserOptions: {
    project: './tsconfig.eslint.json',
    ecmaVersion: 2019,
    sourceType: 'module',
    ecmaFeatures: {
      experimentalObjectRestSpread: true,
    },
  },
  rules: {}, // 自定义
};

module.exports = eslintrc;

yarn add -D rollup rollup-plugin-babel rollup-plugin-commonjs rollup-plugin-eslint rollup-plugin-node-resolve rollup-plugin-typescript2

yarn add -D @babel/preset-env

fly-helper
 |
 |- typings
 	 |- index.d.ts
 |- .babelrc
 |- rollup.config.ts

/* .babelrc */
{
  "presets": [
    [
      "@babel/preset-env",
      {
        /* Babel 会在 Rollup 有机会做处理之前，将我们的模块转成 CommonJS，导致 Rollup 的一些处理失败 */
        "modules": false
      }
    ]
  ]
}

import path from 'path';
import { RollupOptions } from 'rollup';
import rollupTypescript from 'rollup-plugin-typescript2';
import babel from 'rollup-plugin-babel';
import resolve from 'rollup-plugin-node-resolve';
import commonjs from 'rollup-plugin-commonjs';
import { eslint } from 'rollup-plugin-eslint';
import { DEFAULT_EXTENSIONS } from '@babel/core';

import pkg from './package.json';

const paths = {
  input: path.join(__dirname, '/src/index.ts'),
  output: path.join(__dirname, '/lib'),
};

// rollup 配置项
const rollupConfig: RollupOptions = {
  input: paths.input,
  output: [
    // 输出 commonjs 规范的代码
    {
      file: path.join(paths.output, 'index.js'),
      format: 'cjs',
      name: pkg.name,
    },
    // 输出 es 规范的代码
    {
      file: path.join(paths.output, 'index.esm.js'),
      format: 'es',
      name: pkg.name,
    },
  ],
  // external: ['lodash'], // 指出应将哪些模块视为外部模块，如 Peer dependencies 中的依赖
  // plugins 需要注意引用顺序
  plugins: [
    // 验证导入的文件
    eslint({
      throwOnError: true, // lint 结果有错误将会抛出异常
      throwOnWarning: true,
      include: ['src/**/*.ts'],
      exclude: ['node_modules/**', 'lib/**', '*.js'],
    }),

    // 使得 rollup 支持 commonjs 规范，识别 commonjs 规范的依赖
    commonjs(),

    // 配合 commnjs 解析第三方模块
    resolve({
      // 将自定义选项传递给解析插件
      customResolveOptions: {
        moduleDirectory: 'node_modules',
      },
    }),
    rollupTypescript(),
    babel({
      runtimeHelpers: true,
      // 只转换源代码，不运行外部依赖
      exclude: 'node_modules/**',
      // babel 默认不支持 ts 需要手动添加
      extensions: [...DEFAULT_EXTENSIONS, '.ts'],
    }),
  ],
};

export default rollupConfig;

declare module 'rollup-plugin-babel';
declare module 'rollup-plugin-eslint';

export default function myFirstFunc(str: string) {
  return `hello ${str}`;
}

yarn add -D @types/jest eslint-plugin-jest jest ts-jest

fly-helper
 |- test
 	|- index.test.ts
 |- jest.config.js

// jest.config.js
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
};

// index.test.ts

import assert from 'assert';
import myFirstFunc from '../src';

describe('validate:', () => {
  /**
   * myFirstFunc
   */
  describe('myFirstFunc', () => {
    test(' return hello rollup ', () => {
      assert.strictEqual(myFirstFunc('rollup'), 'hello rollup');
    });
  });
});

const eslintrc = {
  // ...
  extends: [
    // ...
    'plugin:jest/recommended',
  ],
  plugins: [
    // ...
    'jest',
  ],
  // ...
};

"test": "jest --coverage --verbose -u"

yarn test

yarn add -D @microsoft/api-extractor

/* api-extractor.json */
{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "mainEntryPointFilePath": "./lib/index.d.ts",
  "bundledPackages": [],
  "dtsRollup": {
    "enabled": true,
    "untrimmedFilePath": "./lib/index.d.ts"
  }
}

"api": "api-extractor run",

/**
 * 返回 hello 开头的字符串
 * @param str - input string
 * @returns 'hello xxx'
 * @example
 * ```ts
 * myFirstFunc('ts') => 'hello ts'
 * ```
 *
 * @beta
 * @author ziming
 */

yarn add -D gulp @types/gulp fs-extra @types/fs-extra @types/node ts-node chalk

  "main": "lib/index.js",
  "module": "lib/index.esm.js",
  "typings": "lib/index.d.js",

  "scripts": {
      /* ... */
      "build": "gulp build",
  }

// 删除 lib 文件
const clearLibFile: TaskFunc = async (cb) => {
  fse.removeSync(paths.lib);
  log.progress('Deleted lib file');
  cb();
};

// rollup 打包
const buildByRollup: TaskFunc = async (cb) => {
  const inputOptions = {
    input: rollupConfig.input,
    external: rollupConfig.external,
    plugins: rollupConfig.plugins,
  };
  const outOptions = rollupConfig.output;
  const bundle = await rollup(inputOptions);

  // 写入需要遍历输出配置
  if (Array.isArray(outOptions)) {
    outOptions.forEach(async (outOption) => {
      await bundle.write(outOption);
    });
    cb();
    log.progress('Rollup built successfully');
  }
};

// api-extractor 整理 .d.ts 文件
const apiExtractorGenerate: TaskFunc = async (cb) => {
  const apiExtractorJsonPath: string = path.join(__dirname, './api-extractor.json');
  // 加载并解析 api-extractor.json 文件
  const extractorConfig: ExtractorConfig =
    await ExtractorConfig.loadFileAndPrepare(apiExtractorJsonPath);
  // 判断是否存在 index.d.ts 文件，这里必须异步先访问一边，不然后面找不到会报错
  const isExist: boolean = await fse.pathExists(extractorConfig.mainEntryPointFilePath);

  if (!isExist) {
    log.error('API Extractor not find index.d.ts');
    return;
  }

  // 调用 API
  const extractorResult: ExtractorResult = await Extractor.invoke(extractorConfig, {
    localBuild: true,
    // 在输出中显示信息
    showVerboseMessages: true,
  });

  if (extractorResult.succeeded) {
    // 删除多余的 .d.ts 文件
    const libFiles: string[] = await fse.readdir(paths.lib);
    libFiles.forEach(async (file) => {
      if (file.endsWith('.d.ts') && !file.includes('index')) {
        await fse.remove(path.join(paths.lib, file));
      }
    });
    log.progress('API Extractor completed successfully');
    cb();
  } else {
    log.error(
      `API Extractor completed with ${extractorResult.errorCount} errors` +
        ` and ${extractorResult.warningCount} warnings`
    );
  }
};

// 完成
const complete: TaskFunc = (cb) => {
  log.progress('---- end ----');
  cb();
};

export const build = series(clearLibFile, buildByRollup, apiExtractorGenerate, complete);

yarn build

yarn add -D conventional-changelog-cli

// gulpfile
import conventionalChangelog from 'conventional-changelog';

// 自定义生成 changelog
export const changelog: TaskFunc = async (cb) => {
  const changelogPath: string = path.join(paths.root, 'CHANGELOG.md');
  // 对命令 conventional-changelog -p angular -i CHANGELOG.md -w -r 0
  const changelogPipe = await conventionalChangelog({
    preset: 'angular',
    releaseCount: 0,
  });
  changelogPipe.setEncoding('utf8');

  const resultArray = ['# 工具库更新日志\n\n'];
  changelogPipe.on('data', (chunk) => {
    // 原来的 commits 路径是进入提交列表
    chunk = chunk.replace(/\/commits\//g, '/commit/');
    resultArray.push(chunk);
  });
  changelogPipe.on('end', async () => {
    await fse.createWriteStream(changelogPath).write(resultArray.join(''));
    cb();
  });
};

// typings/index.d.ts

declare module 'conventional-changelog';

yarn add -D husky lint-staged

  "husky": {
    "hooks": {
      "pre-commit": "lint-staged & jest -u"
    }
  },
  "lint-staged": {
    "*.{.ts,.js}": [
      "eslint",
      "git add"
    ]
  }

/* pushlish 的文件 */
"files": [
    "lib",
    "LICENSE",
    "CHANGELOG.md",
    "README.md"
],
/* 使得支持 tree shaking */
"sideEffects": "false",
"script": {
    /* ... */
    "changelog": "gulp changelog",
    "prepublishOnly": "yarn lint & yarn test & yarn changelog & yarn build"
}