likes
comments
collection
share

如何做一个前端开源项目？

作者站长头像
站长
· 阅读数 10

大家好，我是码农小余。

之前给大家剖析了 npm-run-all 的源码，了解了多命令兼容、参数解析、任务组的任务编排和单任务的执行过程，还没看过的童鞋可以点击链接前往。

虽然看的是一个 6 年前写下第一行代码的仓库，但是意外地发现 npm-run-all 这个开源项目，它的核心要素跟当前新鲜火爆的工具例如 Vitest 等都是一样的，这就是所谓开源项目中不变的核心！本文会结合 npm-run-all 这个包，聊聊开源项目的基本要素：

  • 需求挖掘
  • 代码目录
  • 单元测试
  • 文档门面
  • 宣传&客群
  • 坚持就是胜利……

需求挖掘

npm-run-all 做的事情很简单，目的就是简化两种在 package.json 中的“屎山”代码：

# 并行
$ npm run lint & npm run test & npm run ……
​
# 串行
$ npm run lint && npm run test && npm run ……

当我们要执行的任务数量比较多或者每个任务带有很多参数项时，上述 scripts 无法直视。通过将 npm run 重复的代码消除，简化整个脚本的写法，就是 npm-run-all 的核心功能：

# 并行
$ npm-run-all -p lint test ……
​
# 串行
$ npm-run-all lint test ……

对于需求的挖掘，就只有一条方法：

擦亮自己的眼睛，就能发现身边的“屎山” 。

视而唾之，围而辱之，均未上上之策。

“屎山”是需要被治理的，多思考如何才能解决问题，就是“需求”、“创新”的诞生之地。值得注意的是需求不要设想地太大，毕竟初期是你一个人的战斗，要快速地收到反馈才有动力坚持做下去。愿景想得很大，三五个月都做不完，那铁定是一个失败的开头。

有了需求，就以迅雷不及掩耳之势建仓、发包占坑。

代码目录

建仓首要任务就是先组织代码目录，我们打印 npm-run-all 源码的代码目录如下：

├── .babelrc
├── .eslintrc.json
├── .git
├── .github
├── .gitignore
├── .npmrc
├── .nyc_output
├── .nycrc
├── .travis.yml
├── LICENSE
├── README.md
├── appveyor.yml
├── bin
├── docs
├── jsdoc.json
├── lib
├── node_modules
├── package.json
├── scripts
├── test
└── test-workspace

虽然这是 6 年的前写的代码，但基本元素都具备：

  • docs：工具文档；
  • lib：核心源码，现代工具大多都是用 monorepo 去组织代码，一般会放在 packages 下；
  • scripts：项目脚本，用于在构建、部署或者生成文档等复杂任务；
  • docs：使用文档；
  • test：单元测试目录；
  • README.md：包说明文档，用于在 npm 或者 github 上显示包的关键信息；
  • .travis.yml：编写 CI 脚本任务；

麻雀虽小五脏俱全，上面列举的都是关键的项目目录结构，即使是现代工具，核心也是这些文件结构，拿 Vitest 举例看看：

├── .DS_Store
├── .editorconfig
├── .eslintignore
├── .eslintrc
├── .git
├── .gitattributes
├── .github
├── .gitignore
├── .npmrc
├── .pnpmfile.cjs
├── .tazerc.json
├── .vscode
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── bench
├── docs
├── examples
├── netlify.toml
├── node_modules
├── package.json
├── packages
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
├── scripts
├── shims.d.ts
├── test
└── tsconfig.json

README.md、docs、packages、scripts、test 等都跟 npm-run-all 是一致的，也可以说是工具项目必备的。

单元测试

覆盖率图标是一个开源工具必备的身份证，npm-run-all 的覆盖率身份：

如何做一个前端开源项目？

看到这个图标，都有一种“用得放心，省心”的心理预期。

没有测试的工具别人不敢用，为什么？

  • 因为质量没保障，随便改一个 issue 就会引起老功能异常，谁敢用？
  • 因为别人不敢修改代码，就算有想法，也不敢给你提 PR 吖；
  • 因为每次修改的测试成本都巨大，贡献者还要非常熟悉整个工具的特性才能改代码，这不是坑*么？
  • ……

拥有测试的工具，能带来以下好处：

  1. 单测即文档，通过阅读单测代码能够快速地了解工具的用法；

  2. 质量保证。单测覆盖率越高，用得越安心；

  3. 即使遇到问题，也能信心十足地补充用例然后修改代码；

  4. CI上都会执行单测用例，Reviewer 没看到 CI 通过都不敢合代码：

    如何做一个前端开源项目？ 测试工具就非常多了，任君选择。小余极力推荐 Vitest 和 Cypress，极力推荐同事的文章 Cypress前端测试左移分享!

文档门面

测试用例和文档都是一个开源项目的血液，缺一不可。

简单的工具通过 README.md 就能讲清楚用法，可以不用单独维护一个文档网站。但是随着需求的丰富、需求迭代，一个 README.md 肯定不足以表述所有的用法，即使塞得进，体验也是极差。

那么此时就很有必要建立文档作为项目门面。npm-run-all 的文档如下：

如何做一个前端开源项目？

npm-run-all 是通过 jsdoc 和代码注释生成的文档，虽然比较简陋，安装、使用说明都还是具备的。

现在的文档生态可谓是百花齐放，Storybook、Vitepress 等等。推荐 Vitepress 真滴方便、快捷、好用

如何做一个前端开源项目？

宣传&客群

项目再好，别人不知道有这玩意，也是白搭。创作水文、技术分享等都是不错的宣传手段。当有了一批用户之后，问题自然也就来了。对于问题的运营也非常重要：

  • 统一问题接入，项目通常都会使用 github issue 作为问题输入地；
  • 设定好固定周期去答疑、处理问题，问题处理完了，再定期发包；
  • 不是所有的需求都得接受，明确项目的核心，评审每一个需求，衡量之后再决策；

坚持就是胜利……

功能持续迭代、精力持续投入、问题持续解决、版本持续更新……

想好了就开干吧，极客！