buzzs v0.0.5
buzzs 简介
这是一个具有完整基础设施并且使用 typescript 开发的 javascript 库项目开发模板, 帮助你快速搭建一个自动生成文档的 javascript 工具库.
文档地址：https://www.ibadgers.cn/buzzs/
用法
在任何你想要使用 buzzs 的项目根目录执行命令：
npm install buzzs即可安装，使用方式：
import { add } from 'buzzs';
const sum = add(1, 2); // 3开发文档
主要文件结构
buzz/
│
├── build/
│ └── index.js // 用于自动生成项目入口文件 src/index.ts 的脚本文件
│
├── src/
│ ├── add.ts // 开发的函数文件
│ └── index.ts // 项目打包的入口文件，可以通过脚本自动生成，也可以手动编辑，但优先通过执行脚本生成
│
├── test/ // 测试文件
│
├── vite.config.ts // vite 的配置文件
│
├── typedoc.config.cjs/ // typedoc 的配置文件
│
├── tsconfig.json/ // typescript 的配置文件
│
└── docs/ // 项目文档的文件
├── .vitepress // vitepress 的配置文件和主题等
└── src // 通过 typedoc 自动生成的文档文件开发过程中我们主需要关注 src 目录即可，在这个目录下，创建要开发的方法即可，注意：
请保持文件名和函数名一直。开发方法的过程中，请严格按照 typescript 语义化标准开发，请减少类似于 any 等类型的使用。
请为函数体写好注释，这是我们通过 vitepress 生成文档的关键。具体语法可以参考 typedoc 官网: https://www.typedoc.cn/guides/overview/
命令解析：
{
"scripts": {
"dev": "vite build --watch", // 监听构建
"build": "vite build", // 构建命令
"docs:dev": "concurrently \"typedoc --watch\" \"vitepress dev docs\"", // 实时监听文件变更，生成实时文档
"docs:build": "typedoc && vitepress build docs", // 文当build命令会在docs/.vitepress/dist，生成dist文件包供部署文档用
"docs:preview": "vitepress preview docs", // 预览文档
"update": "node build/index.js", // 开发完成后，生成入口文件
"release": "dotenv release-it", // 部署
"release:ci": "dotenv release-it --ci", // 部署
"demo:web": "vite", // web端测试
"demo:node": "node test/demo.node.js", // node端测试
"test": "vitest" // vitest测试
}
}示例
/**
* @name 这是一个计算俩数相加的方法
* @group 工具函数
* @param a number类型，必传
* @param b number类型，必传
* @returns (number) 返回一个俩数相加后的number
* @example
* ```ts
* console.log(add(2，4)); // 6
* ```
*/
export const add = (a: number, b: number): number => {
return a + b;
};其中 group 字段应该为['数组', '集合', '函数', '语言', '数学', '数字', '对象', 'Seq', '字符串', '实用函数', '其他']。
测试用例
单元测试
单元测试，我们可以通过 vitest,进行单元测试，可以得出覆盖率等，相关测试结果，也可以自己编写测试代码，但是这些都是在 test 目录下进行。
项目测试
项目测试可以通过命令npm link将库创建软链，在需要安装的项目中使用命令npm link buzzs添加到项目中，实际调用即可。
项目搭建流程
所需主要插件
- vite
- typescript
- vitepress
- typedoc
- vitest
创建过程
项目初始化
- 我们通过命令
mkdir buzz创建一个文件夹，这里就是我们 buzz 的工程，然后cd buzz,进入 buzz 文件夹后，通过命令npm init -y, 来初始化一个项目，这时候，将会自动生成一个 package.json 文件。 - 在根目录下创建 src 文件夹，里面创建 index.ts 文件。src/index.ts 这里就是我们开发的文件入口文件：我们在其中写一个加法函数：
export const add = (a: number, b: number): number => {
return a + b;
};- 接下来我们就安装 vite，通过命令 npm install vite --save-dev,并且在根目录下创建 vite.config.js,这里是 vite 的配置文件，打开文件，我们写下:
import { defineConfig } from 'vite';
import path from 'path';
export default defineConfig({
build: {
lib: {
entry: path.resolve(__dirname, 'src/index.ts'),
name: 'buzzs',
formats: ['es', 'cjs', 'iife', 'umd'],
fileName: 'index'
}
},
optimizeDeps: {
entries: []
}
});其中，build 是我们打包构建的配置:
- entry 是打包的入口文件
- name 是未来我们在项目中安装此包后，进入的全局变量
- formats 打包后生成不同产物的不同格式
- 打包产物的名称
打开 package.json 配置命令
{
...,
"type": "module",
"main": "./dist/index.cjs",
"module": "./dist/index.js",
"types": "./dist/index.d.ts",
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview",
}
}到目前为止，我们无论我们运行 npm run dev 还是 npm run build 都能正常运行了，所以接下来，我们就是要支持他 typescript,因为 vite 本身是支持 typescript 的，所以我们在 src/index.ts 写 typescript 语法是没有问题的。但是我们并不能打包得到 index.d.ts 文件，所以，还需要一个插件 vite-plugin-dts,配置在 plugins 中即可。再次运行 npm run build 即可打包出 index.d.ts 文件。此时一个基本的库已经成型，但是这还远远不够。
添加文档
一个 js 库，没有文档，那将是灾难级的，所以，接下来，我们就配置生成一下文档。这个库的名字叫 vitepress.这是一个自定生成 doc 的库，而且还需要配合 typedoc 和 typedoc-plugin-markdown 来自动生成文档。
- 通过命令 npx vitepress init 初始化 docs 文件，就是我们创建成功的文档。所以我们要在 package.json 中配置文档的启动命令。
{
...
scripts: {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
}
...
}注意：如果发现 vitepress 没有安装，请通过命令 npm add vitepress -D 来安装。这样运行命令 npm run docs:dev 就可以在浏览器预览文档了。
自动生成文档
上一步虽然安装了 vitepress，但是，我们并不能自动生成文档，还需要我们手动来编写开发文档，这样效率还是很低，那么可不可以自动生成文档呢？当然可以，typedoc 插件就是干这个的，我们通过为函数编写注释来自动生成文档。
- 首先我们安装 typedoc;
npm install typedoc;这样我们就安装了 vitepress,但是我们想要生成的是 markdown 文档，所以我们还需要另外一个插件，typedoc-plugin-markdown：
npm install typedoc-plugin-markdown concurrently直接安装即可。另外，我们再安装一个插件 concurrently,这个包是同时执行多个命令。到现在为止我们的插件就安装完成。那么下面我们开始配置启动文档命令：
{
...
scripts: {
"docs:dev": "concurrently \"typedoc --watch\" \"vitepress dev docs\" ",
"docs:build": "typedoc && vitepress build docs",
"docs:preview": "vitepress preview docs",
}
...
}- 接下来，我们还要为 typedoc 编写配置文件，我们可以通过手动添加，或者命令来生成 typedoc.config.cjs 文件，然后内容如下：
/** @type {import('typedoc').TypeDocOptions & import('typedoc-plugin-markdown').PluginOptions} */
module.exports = {
entryPoints: ['./src/index.ts'],
out: 'docs/src',
plugin: ['typedoc-plugin-markdown', './docs/.vitepress/theme/typedoc-theme.mjs'],
theme: 'themeExpand',
hideBreadcrumbs: true,
parametersFormat: 'table',
typeDeclarationFormat: 'table',
textContentMappings: {
'label.returns': '返回值类型',
'label.name': '名称',
'label.source': '查看源码',
'label.extends': '继承',
'label.implements': '实现',
'label.type': '类型',
'label.description': '描述',
'kind.typeAlias.plural': '类型别名',
'kind.typeAlias.singular': '类型别名',
'kind.class.plural': '类',
'kind.class.singular': '类',
'kind.interface.plural': '接口',
'kind.interface.singular': '接口',
'kind.module.plural': '模块',
'kind.typeParameter.plural': '类型参数',
'kind.typeParameter.singular': '类型参数',
'label.defaultValue': '默认值',
'kind.function.plural': '函数',
'kind.function.singular': '函数',
'kind.parameter.singular': '参数名',
'kind.parameter.plural': '参数'
}
};这样运行命令npm run docs:dev，在开发函数的时候，就会实时生成文档可以预览了。
单元测试
js 库没有测试是不行的，所以我们这里选用的 vitest 这个库，当然，也可以选择其他的库，比如 jest,mocha，等都是可以的，这里比较简单，我们直接安装，然后配置命令运行即可：
npm install vitepress部署
通过命令npm run docs:build，在docs/.vitepress/目录下生成了dist文件，这就是我们要部署的文件。
- 文档部署
文档的部署，可以是部署到自己的服务器上，也可以是部署到托管平台上，比如 github，render 上等。我们这里的部署是通过 release 这个插件部署，依然是安装，配置命令：
npm install release{
...
"scripts": {
"release": "dotenv release-it",
"release:ci": "dotenv release-it --ci",
}
}具体根据不同平台，部署就好了。
- 在自己的服务器上，只要将自己的域名指向生成的dist文件即可。
- 发布注意设置npm的官网镜像
- 淘宝镜像：npm config set registry https://registry.npm.taobao.org
- npm镜像：npm config set registry https://registry.npmjs.org