现代前端库开发指南系列(三):从说明文档看库的前世今生

js-library-boilerplate:Javascript入门模板-Webpack 4,Babel 7,UMD,热重载等 Javascript库样板 用于Javascript项目的Library Starter Kit 这是一个更强大的库样板。 作为最小的替代方法,请查看 。 :white_medium_star: 产品特点 Webpack 5 通天塔7 热装( npm start ) CSS自动前缀 SASS / SCSS支持 UMD导出,因此您的库可在任何地方使用。 基于 (适用于Vanilla JS库或React库) 开玩笑的单元测试 npm run demo一个准备部署的演示 用于构建的可定制文件头 可配置的postinstall消息 每日依赖关系更新 :package: 入门 git clone https://github.com/hodgef/js-library-boilerplate.git myLibrary npm install :gem_stone: 客制化 运送前,请确保: 编辑LICENSE文件 编辑package.json信息(这些信息将用于生成构建文件的标题) 编辑library: "MyLibrary" ,其库的导出名称位于./config/ 立即下载

前言

我们在工作中很多时候都要做技术选型,去找寻既能满足自己需求又靠谱的第三方库;在前端开源生态季度繁盛的现状下,只要不是太小众的需求,我们很容易就能找到一堆相关的开源库,那我们具体要怎么做决策呢?我的做法是,先阅读开源库的说明文档让自己有一个感性的认识,然后挑选出其中的两三个库来进行更深入更全面的了解。如此说来,这说明文档是不是就很像我们求职时的简历呢?“简历”关都过不了,何谈“offer”啊!

本文将介绍一个库(即不局限于前端领域)所要具备的说明文档,主要包括 README.md、CHANGELOG.md、LICENSE,这些说明文档均需放置于项目的根目录。

README.md

当我们进入 GitHub 中的某一个开源代码仓库页面,除了项目信息、代码目录结构外,最先映入眼帘的就是 README.md 了,可见,其重要性不亚于 index.html 之于一个网站。

README.md 需要满足以下这些要求:

  • 准确(包括字母大小写)命名为README.md
  • 符合 markdown 语法
  • 每个章节都应有标题
  • 中、英文连接处应有空格分隔
  • 使用 markdown 语法包裹代码片段,并注意标注代码段的语言种类,如:
console.log('code in javascript');

必须包含的内容

一份优秀的 README.md 需要包含以下内容:

  • 名称:必须与库的名称保持一致。
  • 简介:以 markdown 语法>开头;尽量保持简洁且字数应少于120;与 GitHub 仓库(如果有的话)和 npm 包(同样是如果有的话)的描述保持一致。
  • 库的安装方法:如何安装本库,在前端领域下通常指如何安装 npm 包或用<script>加载 CDN 资源。
  • 库的使用方法:如何使用本库,可列出最简单的用法,让用户能够以最快的速度把库跑起来,这能够高效地建立起用户的信任。
  • 开源许可协议:本库的版权声明,下文将详细介绍。
  • API:包括库提供的方法、参数、事件等信息。

可选内容

除了以上必须包含的内容外, README.md 中还有一些对用户友好的内容项,这些内容项往往会为你的库增色不少,所以如果可以的话,也请为你的库 README.md 加上:

  • 目录:带锚点跳转的链接,可使用工具自动根据 README.md 的各级标题来生成,详情请参考 github-markdown-toc 。
  • LOGO:一个好的 LOGO 会成为你的库的视觉识别标识,使你的库更容易被用户接受和记住。
  • 徽章:徽章是由 shileds.io 提供的图片,图片上还可以按需附上超链接;徽章通常用于突出描述本项目在外部第三方平台的状态和数据,如项目的持续集成状态(如果本库配置有单元测试的话那一般还会包括代码测试覆盖率)、项目在某平台(前端领域通常指的是 npm)的下载量、项目最新发布的版本号、开源协议等。
  • 浏览器兼容性:如果本库是在浏览器环境下运行的,那么声明本库的浏览器兼容性可以帮助用户快速完成技术选型。
  • 安全风险:用于罗列本库当前已被发现且未解决的安全漏洞及其风险级别,如有绕过的方法也请附上,这同样可以帮助用户快速做技术选型。

CHANGELOG.md

CHANGELOG.md 记录了本库每个正式发布的版本,以及该版本所包含的内容。对于 GitHub 开源库来说, CHANGELOG.md 中的内容应该与 GitHub 中的 releases 保持一致。

CHANGELOG.md 具体包含以下内容:

  • 版本号
    • 新特性(new features)
    • 优化(optimization)
    • Bug 修复(bug fixes)
    • breaking changes
    • 文档(docs)

如果你觉得维护 CHANGELOG.md 比较困难,那么其实也有工具可以从库每次的 commit message 中分析生成 CHANGELOG.md ,但这对 commit message 的规范性有一定要求,本系列后续的文章里会有详细的介绍。

LICENSE

LICENSE 是本库的版权声明,声明用户可以在什么范围内使用、二次开发、商用本库,具有法律效力,一般可以直接声明使用现成的协议,如 GPL / BSD / MIT/ Mozilla / Apache / LGPL 等,本文不打算介绍如何选择合适的协议,可参考《如何选择开源许可证?》。

LICENSE 对于商业项目的技术选型有这一票否定的地位,因为某些开源协议具有传染性,若你的项目使用了这样的开源库,则你的项目也必须开源,这对于商业项目来说几乎是不可接受的。

主流前端框架 React ,就曾因 LICENSE 问题,引发社区强烈不满,并遭到不少大型公司弃用,最终迫于压力下才改用最宽松的 MIT 协议,这才平息了风波。

多语言

请正确评估你所开发的库的用户群体,如果库的用户群体中包含他国人员,请为他们准备好合适语言的说明文档。而对于一个把源码托管在公共代码仓库的开源项目来说,我建议至少准备中英文两套说明文档,这将大大扩展开源库的用户群,毕竟既然辛辛苦苦做出来个开源库,总还是想多收获点 Star 和 Fork 的嘛嘿嘿~~

一般我们将默认一个说明文档是使用英语的,而把使用其它语言的说明文档的文件名上加上 IETF 语言代码,如简体中文的 IETF 语言代码是zh-CN,因此 README.md 的中文文档命名是README.zh-CN.md, CHANGELOG.md 的中文文档命名是CHANGELOG.zh-CN.md,而 LICENSE 则只需要一份英文版的就足够了。

实例项目代码介绍

我会以我最近写的两个开源库:javascript-library-boilerplate 和 vue-directive-window 来作为实例项目代码来辅助介绍。

javascript-library-boilerplate

javascript-library-boilerplate 是一个现代前端生态下快速构建 javascript 库的脚手架(或称种子项目,或称示例代码,看你理解了),本库支持 GitHub 的 repository templates 功能,你可以直接在项目首页点击 Use this template 来直接套用本脚手架的代码来创建你自己的 javascript 库。

vue-directive-window

vue-directive-window 是一个可以快速让模态框(modal)支持类窗口操作的增强库;类窗口操作主要包括三大类:拖拽移动、拖拽调整窗口尺寸、窗口最大化; vue-directive-window 支持以 Vue 自定义指令或是一般 js 类的方式来调用。

vue-directive-window 相对于 javascript-library-boilerplate 来说,更贴近 Vue 生态圈,如果你最近想为 Vue 生态圈添砖加瓦,不妨参考一下本项目。~~~~

系列文章目录(同步更新)

想要阅读更多我的技术文章?请到我的 GitHub 博客 Array-Huang/blog 来,如果对您有帮助的话请 Star&Watch 走一波哈(〃ω)

javascript-library-boilerplate:基于Webpack 4的样板,可为浏览器和节点创建库! 具有Babel 7,Sass,Jest和带有HMR的开发工作区 Javascript库样板 基于Webpack 4的样板创建用于浏览器,Node或BOTH的库! 具有Babel 7,Sass,Jest和带有HMR的开发工作区。 入门 下载 确定您的构建系统是否需要CSS支持(请参见下文) 确定项目目标: web , node或both (请参见下文) 运行npm install 实现它! :rocket: 您需要CSS和Sass支持吗? 如果答案为是,则不执行任何操作。 默认情况下启用。 现在,您可以开始从js模块导入css / sass / scss文件( )。 如果答案是NO,然后删除所有devDependencies以下autoprefixer (包括)中package.json 。 就是这样,希望您不会破坏任何东西 :grinning_face_with_sweat: 现在您可以运行npm install 。 为Web,Node还是同时为两者构建? 系统将根据package.json文件的browser和main字段创建js捆绑package.json 。 仅提供main字段以仅定位到Node.js。 在/ dist( 立即下载

相关推荐

别再死记硬背了!用Amesim HCD库亲手搭建单向阀、锥阀、球阀模型(附详细参数设置)

本文详细介绍了如何使用Amesim HCD库从零构建单向阀、锥阀和球阀的仿真模型,帮助工程师摆脱死记硬背,掌握物理建模的核心技巧。通过实战案例和参数设置指南,读者将学会如何优化阀门动态响应、验证流量特性以及处理旋转运动等独特挑战,提升液压系统设计效率。

weixin_29248611的博客 502

前端常用的文档及组件库

对前端文档以及组件进行总结

weixin_73416102的博客 5918

SCHUNK SVH五指灵巧手 | 熵洛智能

雄克仿真五指机械手产品系列可以如人手操作那般完美地完成抓取操作。电子装置完全集成于腕关节中,使五指机械手几乎可以完成所有的人体手部动作。凭借带有9个驱动器的运动指骨,机械手可高精度地 执行多种抓取操作。富有弹性的抓取表面确保了对物体的可靠抓取。除了开启抓取和操作任务的全新领域之外,雄克还为在五指机械手的手势基础上进行人与机器人的交流开创了无限可能。编辑切换为居中添加图片注释,不超过 140 字(可选)产品特点:机械手有左手或右手两种版本适合移动应用耗能低,使用 24 V DC 在腕关节处完整集成了控制、调节

ShannonTech的博客 1336

文档在线预览(三)使用js前端实现word、excel、pdf、ppt 在线预览

本文主要介绍了word、excel、pdf、ppt等文件纯前端实现在线预览的方式,从本文的测试情况来看前端实现预览最好的效果还是PDF(或者是图片),不会出现一些文字错乱和乱码的问题,所以一般好的方案就是后端配合将不同格式的文件转换成pdf,转成统一的文件格式,再由前端实现预览效果,这样能保留文件的一些样式的效果,同时前端也只用支持一种文件格式的预览,工作量也能大大降低。

fhey的博客 5万+

H3C交换机Console口连接全攻略:从接线到PuTTY配置(附常见问题排查)

本文详细介绍了H3C交换机Console口的连接与配置方法,包括硬件线缆选择、驱动安装、PuTTY参数设置及常见问题排查。特别针对Console转USB线缆的兼容性和驱动安装难点提供实用建议,帮助网络工程师快速掌握串联调试技巧,解决连接中的黑屏、乱码等典型问题。

weixin_42549451的博客 679

PX4 Offboard模式实战避坑:为什么你的Gazebo无人机解锁了却飞不起来?

本文深入解析PX4 Offboard模式下Gazebo无人机解锁后无法起飞的关键原因,提供详细的故障排查流程和调试方法。重点解决MAVROS连接、setpoint消息频率、坐标系一致性等常见问题,帮助开发者快速掌握无人机控制核心技术。

weixin_33461476的博客 328

前端常用文档

前端常用文档

sun~的博客 582

大模型学习路线之多模态模型

​ (Frankly speaking,博主太懒了)章节一只对CLIP、BLIP、BLIP2、InstructBLIP进行了整理,章节二以CLIP、VisualGLM作为实践案例。​ 实际上多模态模型除了CLIP、BLIP、BLIP2、InstructBLIP,还有LLaVA、miniGPT4,以及国内清华的VisualGLM、阿里的Qwen-VL等。(更多多模态原理可以看文末的参考说明)一、多模态模型 & 理论。

2401_86435672的博客 2294

前端开发必备文档

本文尽可能为各大插件、工具、框架等官方文档导航,标注为中文文档参考则为民间有志青年翻译。

2301_79226238的博客 1507

【AI应用实战-OpenCode】OpenCode安装部署(一)

OpenCode是一款2026年流行的开源AI编程工具,兼具轻量代码编辑器和智能编码代理功能。其核心优势包括:完全免费开源(MIT协议)、全平台兼容、支持75+大模型(含本地部署)、内置完整编程功能链(代码补全/Git集成/AI调试等),且所有数据本地存储确保隐私安全。相比Copilot等商业工具,OpenCode提供更自由的模型选择和零门槛使用体验。安装要求Windows10+/macOS12+/Linux主流发行版,仅需200MB空间和4G内存。该工具完美兼容VSCode生态,支持终端/桌面/IDE三种

2437

“组合”的本质,是一场优雅的试错:手把手带你搞懂回溯与递归

刷题不是为了记住代码,而是为了构建“问题->模型->递归->剪枝”的抽象能力。递归调用的结构化思维;回溯法的路径构建和撤销机制;参数控制的边界判断与剪枝技巧;解空间模型的“树状图”画法;这些思想贯穿算法设计和解决复杂问题的全流程。

Echo_Wish 892

前端开发文档汇总

MDN:jQuery:ES6:Nodejs:Webpack:TypeScript:Vue:React:NestJs:微信小程序:UniApp:CSS预处理器:less:Sass:第三方库:Axios:Echarts:Gsap:Three.js:算法:

qq_59054812的博客 566

黑猫带你学eMMC协议第12篇:生产状态感知(PSA)

1 概述 1.1 什么是PSA Production State Awareness (PSA) 生产状态感知 e•MMC设备可以利用其是否在生产环境中的信息,从而在现场运作时进行不同的操作。 例如,在设备低温焊接(soldering)前,将数据写入emmc,可能导致数据出错,而正在焊接期间写入数据,出错的概率可能会更大。在低温焊接之前,emmc设备可以使用一种特定的内部操作去加载内容,这样就能减少数据出错的概率,而在低温焊接后进行常规的操作就行了。 1.2 psa如何进行工作? PSA存在于emmc5.0

黑猫奥利奥的博客 4264

前端传中文文件名_现代前端库开发指南系列(三):从说明文档看库的前世今生...

前言我们在工作中很多时候都要做技术选型,去找寻既能满足自己需求又靠谱的第三方库;在前端开源生态季度繁盛的现状下,只要不是太小众的需求,我们很容易就能找到一堆相关的开源库,那我们具体要怎么做决策呢?我的做法是,先阅读开源库的说明文档让自己有一个感性的认识,然后挑选出其中的两三个库来进行更深入更全面的了解。如此说来,这说明文档是不是就很像我们求职时的简历呢?“简历”关都过不了,何谈“offer”啊!本...

weixin_39585795的博客 94

迈瑞BS系列全自动生化分析仪LIS协议接口手册(内含HL7和ASTM)

迈瑞BS系列全自动生化分析仪LIS协议接口手册,内含HL7和ASTM)

ET2012新版免狗免安装绿色软件

ET2012新版免狗免安祖昂绿色软件。,新界面,新视觉,

现代前端库开发指南系列(一):融入现代前端生态

本系列文章讲什么内容? 本系列文章主要介绍如何在现代前端生态下,创建一个工业级别的库。近几年来,前端工程化、模块化、组件化的大潮铺天盖地而来,在解决以往的架构痛点之余,却又产生了信息过载的问题;我希望通过分享自己的经验,帮助大家少踩坑多出活。 为什么需要开发一个前端库呢? 在项目开发过程中,总有一些功能是相同或类似的,如果你只是单纯地复制粘贴这部分代码,那么恭喜你,假以时日,需求一改,你就只能自尝...

实用至上 321

最新的sdio 4.0 spec 协议标准 带书签 高清完整PDF版

Part-E1-SDIO-Specification-Ver4.00-Final-120220.pdf:最新的sdio 4.0 spec 协议标准 带书签 高清完整PDF版,包括SDIO 接口的外设,SDIO 接口官方协议等。

【SAP】前世今生系列(六)「ABAP技术栈简介」

各位小伙伴们大家好呀,本文主要介绍的是SAP ABAP的技术栈,以及谈谈我个人对ABAP技术栈的一个理解。希望能够对大家有所启发。

Thunder Wang的博客 8504

《#号的前世今生:一段关于前端路由的“不刷新“往事》

// 根据当前URL渲染不同内容case '/':app.innerHTML = '<h1>首页</h1>';break;app.innerHTML = '<h1>关于我们</h1>';break;

2401_88361338的博客 428

CSS => CSS的前世今生浅谈

作者 | 夏之安然 在2019年的今天,我们能在网上看到炫酷的动画加载,精彩绝伦的交互效果,以及从 PC 端到移动端的响应式交互,大家觉得习以为常。可你不知道的是,在 20 多年前,网页仅仅提供了文档展示能力,没有装饰的它就像一张黑白报纸那样简陋。 你是否会问:网页是如何变成像今天这样精美的? 这就归功于 CSS 了。   CSS 的诞生   20 世纪 90 年...

余光的博客 725

SpringMVC源码剖析(二)- DispatcherServlet的前世今生

原文:http://my.oschina.net/lichhao/blog/100138 上一篇文章《SpringMVC源码剖析(一)- 从抽象和接口说起》中,我介绍了一次典型的SpringMVC请求处理过程中,相继粉墨登场的各种核心类和接口。我刻意忽略了源码中的处理细节,只列出最简单的类甚至是接口类,目的就是让大家先从最高层次的抽象意义上来审视SpringMVC这个框架;我也刻意将Spri

至尊宝 536

DispatcherServlet的前世今生(二)

上一篇文章我介绍了一次典型的SpringMVC请求处理过程中,相继粉墨登场的各种核心类和接口。我刻意忽略了源码中的处理细节,只列出最简单的类甚至是接口类,目的就是让大家先从最高层次的抽象意义上来审视SpringMVC这个框架;我也刻意将SpringMVC和Struts2做对比,目的是让大家看到,SpringMVC究竟吸取了Sturts2设计思想中的哪些精华,又弥补了它的哪些遗憾。 DispatcherServlet作为SpringMVC的核心之中的核心类,再怎么强调它的重要性也不为过。SpringMVC所有

Jay的博客 208
上一篇: 现代前端库开发指南系列(二):使用 webpack 构建一个库
array_huang
博客等级 码龄11年 15粉丝 32原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值