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 | 简体中文

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, 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

Examples

Here are projects currently using this template:

tianjie Documentation: https://tianjie.hacxy.cn

Using the Template

Create the Template Locally

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-complete

Install Dependencies

cd my-utils
npm install

Development

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:build

Release

When executing release command, it will be published using release-it tool

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 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.

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 https://github.com/hacxy/tianjie/blob/main/src/index.ts

hacxy / library-complete-template Goto Github PK