前端工程化实践：使用 TypeDoc 与 Vite 搭建自动化 API 文档站

// src/cache.ts

export interface CacheOptions {
  /** 缓存过期时间（毫秒） */
  ttl: number;
  /** 是否启用本地持久化存储 */
  persistent?: boolean;
}

/**
 * 通用前端内存缓存类
 * 
 * @example
 * ```ts
 * const cache = new MemoryCache<string>({ ttl: 5000 });
 * cache.set('token', 'abc-123');
 * const val = cache.get('token');
 * ```
 */
export class MemoryCache<T> {
  private store = new Map<string, { value: T; expire: number }>();
  private options: CacheOptions;

  constructor(options: CacheOptions) {
    this.options = options;
  }

  /**
   * 写入缓存数据
   * 
   * @param key - 缓存唯一标识符
   * @param value - 需要存储的值
   * @returns 写入是否成功
   */
  public set(key: string, value: T): boolean {
    const expire = Date.now() + this.options.ttl;
    this.store.set(key, { value, expire });
    return true;
  }

  /**
   * 获取缓存数据
   * 
   * @param key - 缓存唯一标识符
   * @returns 返回对应数据，若已过期则返回 undefined
   */
  public get(key: string): T | undefined {
    const data = this.store.get(key);
    if (!data) return undefined;
    if (Date.now() > data.expire) {
      this.store.delete(key);
      return undefined;
    }
    return data.value;
  }
}

pnpm add -D typedoc typedoc-plugin-markdown vitepress

{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "plugin": ["typedoc-plugin-markdown"],
  "readme": "none",
  "excludePrivate": true,
  "excludeProtected": true,
  "githubPages": false
}

.
├── docs/
│   ├── .vitepress/
│   │   └── config.mts
│   ├── api/          # TypeDoc 自动生成的 Markdown 产物
│   └── index.md      # 首页
├── src/
│   └── index.ts
├── package.json
└── typedoc.json

import { defineConfig } from 'vitepress';

export default defineConfig({
  title: 'My Project Docs',
  description: '前端工具库 API 文档',
  themeConfig: {
    nav: [
      { text: '指南', link: '/guide/' },
      { text: 'API 参考', link: '/api/' }
    ],
    sidebar: {
      '/api/': [
        {
          text: 'API 目录',
          // 可以在这里引入 TypeDoc 生成的模块列表
          items: [
            { text: 'MemoryCache', link: '/api/classes/MemoryCache' },
            { text: 'CacheOptions', link: '/api/interfaces/CacheOptions' }
          ]
        }
      ]
    },
    socialLinks: [
      { icon: 'github', link: 'https://github.com/your-org/your-repo' }
    ]
  }
});

{
  "scripts": {
    "docs:gen": "typedoc",
    "docs:dev": "npm run docs:gen && vitepress dev docs",
    "docs:build": "npm run docs:gen && vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

name: Deploy Documentation

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 9

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build Docs
        run: pnpm docs:build

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4