Library Complete Template

这是一个具有完整基础设施并且使用 typescript 开发的 javascript 库项目开发模板, 帮助你快速搭建一个自动生成文档的 javascript 工具库.

English | 简体中文

特点

• 开箱即用, 具备完整的基础设施, 无复杂配置
• 使用 typescript 开发, 我们都喜欢 type
• 极快的, 使用 vite 构建, 享受 vite 带来的极速体验
• 注释即文档, 使用 typedoc 以及 typedoc-plugin-markdown自动输出 markdown 文档, 并交给 vitepress 驱动
• 使用 vitest 进行单元测试, 更友好的测试体验, 支持 ui 模式

示例

以下是正在使用这个模板的项目:

• tianjie 文档: https://tianjie.hacxy.cn

使用模板

将模板创建至本地

• 您可以使用 vitepress-ssg 快速的将项目创建至您的本地

执行创建命令时可以通过选项指定项目名称和模板名称

# npm 7+, 需要额外的双破折号:
npm i vitepress-ssg@latest 

# yarn：
yarn add vitepress-ssg my-utils 

# pnpm：
pnpm i vitepress-ssg my-utils --template library-complete



### 安装依赖

```sh
cd my-utils
npm install

开发

• 开发模式:

  这将开启监听模式为将 ts 文件打包至 dist 目录

  npm run dev

• 打包生产环境代码

  npm run build

• 运行单元测试

  npm run test

• 运行具有可视化操作界面的单元测试

  npm run test:ui

• 运行浏览器环境的 demo

  npm run demo:web

• 运行 node 环境的 demo

  npm run demo:node

• 开发文档

  npm run docs:dev

• 打包文档

  npm run docs:build

发布

执行发布命令时, 将使用 release-it 工具发布

npm run release |
npm publish    

文档如何生成

当执行 npm run docs:dev 时,typedoc 会开启监听模式, 并根据所有导出的方法生成 markdown 文档至 docs/src 目录, 同时 vitepress 开发模式将会启动, 你可以通过http://localhost:5173/预览你的文档内容

文档内容还可以在方法的注释中补充, 但是需要注意, 注释内容应该按照 typedoc 规范来编写. 以下是一个示例:

/**
 * @name 这是一个说hello的方法
 * @group 工具函数
 * @param name 名称
 * @returns
 * @example
 * ```ts
 * console.log(sayHello('hacxy')); // Hello, hacxy!
 * ```
 */
export const sayHello = (name: string): string => {
  return `Hello, ${name}!`;
};

在这段示例中, 我们丰富了该方法在文档的标题、分组、 参数说明, 以及代码示例, 如果您之前编写过 jsdoc 注释那么应该对此并不会感到陌生, 但是如果您是第一次接触, 请参考 typedoc 来学习如何编写. 另外在注释中我们还可以使用 markdown 语法, 当你使用 markdown 语法时会将 markdown 内容直接渲染至文档中.

上述示例中所用的 tag 作用:

• @name 方法名
• @group 方法所属分组, 这个属性会额外的影响文档的侧边导航栏
• @param 参数说明
• @returns 返回值说明
• @example 代码示例

你不应该去修改 docs/src 目录下的任何文件, 因为这些文件都是通过 typedoc 生成的. 它们最终都会被 vitepress 驱动.

开发规范

所有模块都应该统一在src/index.ts被导出, 这样 vite 才能找到这个入口为你构建正确的 js 代码, 同时 typedoc 也是通过这个入口来为模块生成文档的.

如果你对此还不是很清楚, 那么可以查看目前正在使用此模板的项目: https://github.com/hacxy/tianjie/blob/main/src/index.ts

typedoc: https://typedoc.org/ typedoc-plugin-markdown: https://typedoc-plugin-markdown.org/docs vite: https://vitejs.dev/ vitepress: https://vitepress.dev/ vitest: https://vitest.dev/