This is a JavaScript library project development template with complete infrastructure and developed using TypeScript to help you quickly build a JavaScript utility library that automatically generates documentation.
English | 简体中文
- Out-of-the-box, with complete infrastructure, no complex configuration required
- Developed using TypeScript because we all love types
- Extremely fast, built using vite, enjoy the lightning-fast experience brought by Vite
- Comments as documentation, automatically output markdown documents using typedoc and typedoc-plugin-markdown, driven by vitepress
- Unit testing with vitest for a more user-friendly testing experience, supporting UI mode
Here are projects currently using this template:
- tianjie Documentation: https://tianjie.hacxy.cn
You can quickly create the project locally using create-ts-frame
When executing the creation command, you can specify the project name and template name through options.
# npm 7+, requires additional double dashes:
npm create ts-frame@latest my-utils -- --template library-complete
# yarn:
yarn create ts-frame my-utils --template library-complete
# pnpm:
pnpm create ts-frame my-utils --template library-complete
# Bun:
bun create ts-frame my-utils --template library-completecd my-utils
npm install- Development mode:
This will start watching for TS files to bundle into the dist directory.
npm run dev- Build production code
npm run build- Run unit tests
npm run test- Run unit tests with visual interface
npm run test:ui- Run web demo in browser environment
npm run demo:web- Run node demo in node environment
npm run demo:node- Develop documentation
npm run docs:dev- Package documentation
npm run docs:buildWhen executing release command, it will be published using release-it tool
npm run releaseWhen executing npm run docs:dev, typedoc will start in watch mode, and generate markdown documents for all exported methods to the docs/src directory. At the same time, vitepress development mode will be launched, and you can preview your document.
Additional documentation content can also be supplemented in method comments, but it is important to note that the comment content should be written according to the typedoc specifications. Here is an example:
/**
* @name This is a method that says hello.
* @group Utility functions.
* @param name Name.
* @returns
* @example
* ```ts
* console.log(sayHello('hacxy')); // Hello, hacxy!
* ```
*/
export const sayHello = (name: string): string => {
return `Hello, ${name}!`;
};In this example, we enrich the method in the document's title, grouping, parameter description, and code examples. If you have written JSDoc comments before, this should not be unfamiliar to you. However, if you are new to it, please refer to TypeDoc for learning how to write.
Additionally, in comments we can also use Markdown syntax. When using Markdown syntax, the content will be rendered directly into the document.
The tags used in the above example:
-
@name: Method name
-
@group: Group that the method belongs to; this property will additionally affect the side navigation bar of the document
-
@param: Parameter description
-
@returns: Return value description
-
@example: Code example
You should not modify any files under docs/src directory because these files are generated by TypeDoc. They will eventually be driven by VitePress.
All modules should be uniformly exported in src/index.ts, so that Vite can find this entry point to build correct JS code for you and TypeDoc also generates documentation for modules through this entry point.
If you are still unclear about this, you can check out a project currently using this template at https://github.com/hacxy/tianjie/blob/main/src/index.ts