从零到一搭建一个前端工具函数库

大家的阅读是我发帖的动力，本文首发于我的博客：deerblog.gu-nami.com/，欢迎大家来玩喵，

转载请注明出处。

🎈前言

工具函数库为开发人员提供高效、便捷的工具函数，简化开发流程，减少模板代码，提高代码质量和可维护性。在团队协作或长期维护的项目中，工具函数库是提升开发效率的关键环节。

本文将手把手教你如何从零搭建一个强类型、易维护的前端工具函数库。这篇博客以我的开源项目 Parsnip-Kit 为例，解析搭建前端工具函数库的技术。

Parsnip-Kit 这个库主要是把开发中遇到的较常用的函数进行一个整合，形成的一个工具库。它是一个零依赖、多功能、模块化的 JavaScript 工具库，支持 TypeScript。

Github：https://github.com/shika-space/parsnip-kit

文档站点：https://shika-space.github.io/parsnip-kit/

🎇项目架构全景

问了一下 AI，一个优秀的工具函数库应该具备：

• 模块化设计：按功能领域划分模块
• 类型友好：完善的 TypeScript 类型声明
• 高质量保障：单元测试覆盖率 > 95%
• 开箱即用：支持多种模块化方案（ESM/CJS/UMD）
• 开发友好：完整的文档和示例代码

Parsnip-Kit 也符合这些要求，Parsnip-Kit 项目基于现代构建工具 Vite 构建，结合了 Vitest 单元测试和 ESLint + Prettier 代码规范，保证项目迭代更新中保持代码质量。

除此之外，我使用了 VitePress 搭建文档站点，基于 inquirer 搭建了新建模块脚手架，基于 comment-parser 搭建的文档生成工具，减少了迭代更新中的重复操作。
--- title: config: theme: default --- graph TB O[项目架构]---A[类型安全]---TypeScript O---C[构建方案]---Vite C---dts-bundle-generator O---D[单元测试]---Vitest O---E[代码规范]---Eslint E---Prettier O---F[Git 工作流]---Husky F---Lint-Staged O---G[脚手架]---Inquirer O---H[文档生成]---Comment-Parser O---I[文档站点]---VitePress linkStyle 0 stroke:#9370DB,stroke-width:2px linkStyle 1 stroke:#9370DB,stroke-width:2px linkStyle 2 stroke:#9370DB,stroke-width:2px linkStyle 3 stroke:#9370DB,stroke-width:2px linkStyle 4 stroke:#9370DB,stroke-width:2px linkStyle 5 stroke:#9370DB,stroke-width:2px linkStyle 6 stroke:#9370DB,stroke-width:2px linkStyle 7 stroke:#9370DB,stroke-width:2px linkStyle 8 stroke:#9370DB,stroke-width:2px linkStyle 9 stroke:#9370DB,stroke-width:2px linkStyle 10 stroke:#9370DB,stroke-width:2px linkStyle 11 stroke:#9370DB,stroke-width:2px linkStyle 12 stroke:#9370DB,stroke-width:2px linkStyle 13 stroke:#9370DB,stroke-width:2px linkStyle 14 stroke:#9370DB,stroke-width:2px linkStyle 15 stroke:#9370DB,stroke-width:2px linkStyle 16 stroke:#9370DB,stroke-width:2px linkStyle 17 stroke:#9370DB,stroke-width:2px linkStyle 18 stroke:#9370DB,stroke-width:2px

🧨类型安全：TypeScript

TypeScript 作为 JavaScript 的超集，为开发带来了诸多优势。它通过添加静态类型系统，在编译阶段就能对代码进行类型检查，有效预防错误，减少运行时出现的bug。TS 提供的类型约束、类型推导，也为使用者提供了清晰的指引。

✨构建方案：Vite

Vite 是一个现代的前端构建工具，对 TypeScript 有很好的支持，提供了极快的开发体验。

作为一个工具库，我们需要的是库模式打包，Parsnip-Kit 的项目打包配置如下，它支持了 ESModule、CommonJs、UMD 3 种模块规范，使得库可以用在不同模块规范的场景中：

import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'

const __dirname = dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  // ...
  build: {
    lib: {
      entry: resolve(__dirname, 'packages/main.ts'),
      name: 'parsnip-kit',
      fileName: 'parsnip-kit',
      formats: ['es', 'umd', 'cjs']
    },
  },
})

生成 dts 文件一般是用 vite-plugin-dts，在 Vite 5 上，这个插件跑不起来了，这里改成用 dts-bundle-generator。

npm i dts-bundle-generator -D

在根目录新建 dts-bundle-generator.config.json

{
  "compilationOptions": {
    "preferredConfigPath": "./tsconfig.json"
  },
  "entries": [
    {
      "filePath": "./packages/main.ts",
      "outFile": "./dist/parsnip-kit.d.ts"
    }
  ]
}

构建的命令这么写就好了:

{
  "scripts": {
    "build": "vite build && npx dts-bundle-generator -config dts-bundle-generator.config.json"
  }
}

🎉单元测试：Vitest

Vitest 是一个轻量级的测试框架，它与 Vite 无缝集成，能够快速运行测试用例。重要的是 Vitest API 设计与 Jest 保持一致，整合了 v8、Istanbul 等测试覆盖率统计工具，拥有多种报告输出器，使得我们可以一站式地完成单元测试配置。

下面是 Parsnip-Kit 的项目的 Vitest 配置，它使用了默认的 v8 统计测试覆盖率，并且使用了 JSON 报告器输出，以便后续在文档中展示测试覆盖率：

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    reporters: ['json', 'default'],
    outputFile: 'coverage/coverage.json',
    exclude: ["node_modules", "dist", "script"],
    coverage: {
      exclude: ["node_modules", "dist", "script", "packages/common/types.ts"],
      include: ["packages"],
    }
  },
  // ...
})

🎊代码规范体系：ESLint + Prettier

ESLint 主要是代码质量的代码检查工具。它在 v8.53.0 版本后，移除了所有代码风格的检查，我们也不用过多考虑它和 Prettier 的冲突问题了。Prettier 专注于对代码风格进行处理。

参考这篇博客:ts 项目如何从 ESlint8 升级至 ESlint9 并集成 Prettier 的最新写法，Parsnip-Kit 项目使用了 ESLint + Prettier，并且让它们支持 TypeScript 的检查。

先安装这些依赖：

npm i eslint eslint-config-prettier eslint-plugin-prettier typescript-eslint -D

在根目录新建 eslint.config.js，这是项目的配置：

import js from "@eslint/js"
import globals from "globals"
import tseslint from "typescript-eslint"
import eslintConfigPrettier from "eslint-config-prettier"
import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended"

export default tseslint.config({
  extends: [
    js.configs.recommended,
    ...tseslint.configs.recommended,
    eslintConfigPrettier,
    eslintPluginPrettierRecommended,
  ],
  files: ["**/*.{ts,js}"], // eslint 检测的文件，根据需要自行设置
  ignores: ["dist", "node_modules"],
  languageOptions: {
    ecmaVersion: 2020,
    globals: globals.browser,
  },
  rules: {
    "prettier/prettier": ["warn", {
      "semi": false,
      "singleQuote": true,
      'trailingComma': 'none'
    }], // 默认为 error
    "arrow-body-style": "off",
    "prefer-arrow-callback": "off",
    "@typescript-eslint/no-explicit-any": "off", // allow any type
    "@typescript-eslint/no-unsafe-function-type": "off",
    "prefer-rest-params": "off",
    "@typescript-eslint/no-this-alias": "off",
    "@typescript-eslint/ban-ts-comment": "off"
  },
})

然后就加入检测的命令到 package.json

{
  "scripts": {
    "lint": "npx eslint packages/",
    "lint:fix": "npx eslint packages/ --fix",
  }
}

🔧Git 工作流：Husky

Husky 是一个可以在 git 钩子中执行代码的工具，我们可以在 git 钩子中，执行代码检查，保证提交代码的质量。

npm install husky -D
npx husky init

在项目根目录 .husky 文件夹中可以看到一个 pre-commit 文件，这里可以填入在提交之前执行的命令。

我们如果直接 npm run lint:fix 势必会涉及到未提交内容在内的所有文件。为了只检查已添加到 Git 中的文件，我们需要 lint-staged。

npm install lint-staged -D

之后在 package.json 添加以下配置：

{
  "lint-staged": {
    "*.{js,ts}": [
      "eslint --fix",
      "git add"
    ]
  }
}

这样子就可以在提交时对代码进行检查和修复了。

🎁脚手架：Inquirer

inquirer 是用于搭建命令行交互式问答的工具，利用它，我们可以通过简单的选项和输入，在项目中新增一个模块或者函数。举个简单的例子：

在用户输入完后，拿到回答再去新建相应的文件就好了。

下面就是这段对话的关键代码，详情请看这里：init.js。

const getSelectedModule = async () => {
  const modules = getPackageModules();
  
  const choices = modules.map(module => ({
    name: module,
    value: module
  }));
  
  choices.push({
    name: 'Create a new module',
    value: 'new'
  });
  
  const answers = await inquirer.prompt([{
    type: 'list',
    name: 'module',
    message: 'Please select or create a module:',
    choices: choices
  }]);
  
  if (answers.module === 'new') {
    const newModuleAnswer = await inquirer.prompt([{
      type: 'input',
      name: 'newModuleName',
      message: 'Please enter the name of the new module:',
      validate: input => {
        if (/^[a-zA-Z]+$/.test(input)) {
          return true;
        }
        return 'Module name must be in English';
      }
    }]);
    
    return newModuleAnswer.newModuleName;
  }
  
  return answers.module;
};

📚文档生成：Comment-Parser

Parnip-Kit 的文档生成是借助 comment-parser 解析函数上的 JSDoc 注释，然后结合借助上文中脚手架生成的 markdown 模板文件完成的。

这个思路主要来自掘金上的这篇博客：开源一个可以将带有JSDoc注释的JS或TS文件转换为markdown的工具，作者把 JSDoc 转换为了 markdown 文档，极大简便了文档的维护。

但是这种方式也有不满足 Parsnip-Kit 场景的地方，我们的文档支持了多语言，如果按照这种方式，需要在注释中写一大堆多语言的东西，比较影响维护。后面参考了 Element-Plus 等组件文档的方法，函数的入参、返回以及简单的描述写在 JSDoc 注释中，在 markdown 模板中去嵌入它们。多语言和文档的更多详细描述转移到在 markdown 模板文件中完成。详见 generateMd.js。

举个例子：

函数文件：

/**
 * Splits array `arr` into sub-arrays with the length of `length`.
 * @template {} T Type of elements of array to split
 * @param {T[]} arr The array to split
 * @param {length} length The length of sub-arrays
 * @returns {T[][]}
 * @version 0.0.2
 */

export function chunk<T>(arr: T[], length: number) {
  // ...
}

中文的 markdown 模板：

# chunk
[[[desc chunk
  将数组 `arr` 分割成长度为 `length` 的子数组。
]]]
[[[version chunk]]]
### Usage
```ts
import { chunk } from 'parsnip-kit'

const arr = [1, 2, 3, 4, 5]
chunk(arr, 2)
// [[1, 2], [3, 4], [5]]
\`\`\`
// 实际文件中 \`\`\` 没有 \ 符号，主要是因为不这样写在博客上 md 解析会出问题
### API
#### Type Parameter
[[[template chunk
  T: 要分割的数组的元素类型
]]]
#### Arguments
[[[params chunk
  arr: 要分割的数组
  length: 子数组的长度
]]]
#### Returns
[[[returns chunk]]]

🎗文档站点：VitePress

VitePress 是 Vite 官方推出的一个静态站点生成器，特别适合用于构建技术文档站点。支持 Markdown 和 Vue 组件，允许我们在文档中嵌入交互式的示例和组件，增强文档的可读性和实用性。

这里内容比较多，下次再展开说，这是 Parsnip-Kit 的效果，站点：https://shika-space.github.io/parsnip-kit/

🧸结语

通过本文的完整技术方案，您也可以打造属于自己的工具库。

Parsnip-Kit 最早是为了减少自己开发中的模板代码而设计的，现在开源并且持续迭代，欢迎 Star ⭐ 和贡献代码！

Github：https://github.com/shika-space/parsnip-kit

文档站点：https://shika-space.github.io/parsnip-kit/