https://github.com/hacxy/library-complete-template
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.
https://github.com/hacxy/library-complete-template
template typescirpt-library typescript-template
Last synced: 5 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/hacxy/library-complete-template
- Owner: hacxy
- Created: 2024-04-12T05:23:56.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-07-06T10:40:44.000Z (11 months ago)
- Last Synced: 2024-07-06T11:47:19.922Z (11 months ago)
- Topics: template, typescirpt-library, typescript-template
- Language: JavaScript
- Homepage:
- Size: 205 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Library Complete Template
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 | [简体中文](https://github.com/hacxy/library-complete-template/blob/main/README_zh.md)
## Features
- Out-of-the-box, with complete infrastructure, no complex configuration required
- Developed using TypeScript because we all love types
- Extremely fast, built using [vite](https://vitejs.dev/), enjoy the lightning-fast experience brought by Vite
- Comments as documentation, automatically output markdown documents using [typedoc](https://typedoc.org/) and [typedoc-plugin-markdown](https://typedoc-plugin-markdown.org/), driven by [vitepress](https://vitepress.dev/)
- Unit testing with [vitest](https://vitest.dev/) for a more user-friendly testing experience, supporting UI mode
## Examples
Here are projects currently using this template:
- [tianjie](https://github.com/hacxy/tianjie) Documentation:
## Using the Template
### Create the Template Locally
You can quickly create the project locally using [create-ts-frame](https://github.com/hacxy/create-ts-frame)
When executing the creation command, you can specify the project name and template name through options.
```sh
# 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-complete
```
### Install Dependencies
```sh
cd my-utils
npm install
```
### Development
- Development mode:
This will start watching for TS files to bundle into the `dist` directory.
```sh
npm run dev
```
- Build production code
```sh
npm run build
```
- Run unit tests
```sh
npm run test
```
- Run unit tests with visual interface
```sh
npm run test:ui
```
- Run web demo in browser environment
```sh
npm run demo:web
```
- Run node demo in node environment
```sh
npm run demo:node
```
- Develop documentation
```sh
npm run docs:dev
```
- Package documentation
```sh
npm run docs:build
```
### Release
When executing release command, it will be published using [release-it](https://github.com/release-it/release-it) tool
```sh
npm run release
```
## How to generate documents
When 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](https://typedoc.org/guides/overview/) specifications. Here is an example:
````ts
/**
* @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](https://typedoc.org/guides/overview/) 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.
## Development Specification
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