WebFont — Runtime Font Delivery + AI Chinese Font Skill

Subset Chinese fonts on demand — 6 characters ≈ 6KB. Use premium Chinese fonts on any web page.

中文

Chinese fonts are huge (Source Han Sans: 16MB+). You can't just @font-face them like English fonts.

This project subsets fonts on the server side — pass in the text you need, get back only those glyphs. A poster with 20 characters? The font file is 20KB, not 16MB.

<!-- One CSS block to use any Chinese font -->
<style>
@font-face {
  font-family: "MyFont";
  src: url("https://webfont.shenzilong.cn/api?font=令东齐伋复刻体&text=静心茶舍&outType=ttf") format("truetype");
}
.title { font-family: "MyFont", serif; }
</style>
<h1 class="title">静心茶舍</h1>

Who Is This For

Any project that needs Chinese Web Fonts:

• Posters / H5 pages — a few characters subset to a few KB
• Brand websites — premium fonts no longer limited by file size
• Mini apps / PWA — bandwidth-sensitive, load on demand
• Static blogs / CMS — content is known, CSS-only output
• AI-generated pages — let AI output well-designed Chinese font solutions

Features

Live Font Demo — same content, different fonts, completely different feel

Runtime Font Delivery

Server-side subsetting + client-side incremental loading.

6 characters → server subsets font → returns ~6KB (not 16MB)

Subsetting performance (Node.js benchmark, Lingdong Qiji Fuke, avg of 50 rounds):

Case	ttf	woff2	Output size
Latin + digits (Hello World 123)	0.11ms	0.13ms	0.4KB
8 CJK characters	0.17ms	0.38ms	8KB
Thousand Character Classic excerpt (88 chars)	0.37ms	2.11ms	78KB

Small character sets (the common case) hit sub-millisecond subsetting; time scales linearly with glyph count, with woff2's extra cost from brotli compression (a native hard limit). Response headers X-Timing-Find/Read/Subset/Total expose per-stage timing.

JS SDK with three loading modes:

<script src="https://webfont.shenzilong.cn/webfont-sdk.js"></script>
<script>
  // Recommended: MutationObserver-driven, auto-loads new characters on DOM change
  WebFont.observeFont({ fontName: "令东齐伋复刻体.ttf", selector: ".content", family: "MySerif" });

  // Polling mode
  WebFont.loadFont({ fontName: "令东齐伋复刻体.ttf", selector: ".title", family: "MySerif" });

  // Manual text mode
  var loader = WebFont.loadText({ fontName: "令东齐伋复刻体.ttf", text: "你好世界", family: "MySerif" });
  loader.update("追加文字");
</script>

All modes share the same character set per font — zero duplicate requests, zero flicker.

AI Chinese Font Skill

Inject Chinese font application capability into AI (Claude, Cursor, Copilot, etc.). With the Skill Prompt, AI can:

• Auto-select fonts matching the scene
• Handle Chinese-English mixed typesetting
• Build proper font hierarchy
• Generate fallback chains and runtime loading strategies

Prompt: "Build a zen-style tea brand website"

Without Skill: font-family: sans-serif → system default → looks generic

With Skill: zen style → serif heading + kai body → auto subset → visual quality leap

Quick Start

API Only

No SDK needed. One CSS block to use any Chinese font. Server returns only the character subset you need.

@font-face {
  font-family: "MyFont";
  src: url("https://webfont.shenzilong.cn/api?font=令东齐伋复刻体&text=你的文字&outType=ttf") format("truetype");
}

Self-hosted

# Node.js / LLRT
pnpm install && pnpm build && pnpm build_backend
node ./dist_backend/app.cjs

Docker (~30MB image):

services:
  webfont:
    image: docker.io/llej0/web-font:latest
    ports:
      - "8087:8087"
    volumes:
      - ./fonts:/home/font
    environment:
      - ENABLE_TEMP_UPLOAD=true
      - ADMIN_API_KEY=your-secret-key
      - SUBSET_CACHE_MAX_SIZE=10485760
      # Temp font retention (seconds), auto-deleted if unused. Default: 10800 (3h)
      - TEMP_RETENTION_SECONDS=10800
      # Max concurrent font subsetting. Default: 4
      - SUBSET_CONCURRENCY=4

API Reference

Endpoint	Description
GET /api?font={name}&text={chars}&outType={woff2|ttf}	Subset font to specified characters
GET /api/fonts	List available fonts
GET /api/config	Get server configuration
POST /api/upload?mode=temp	Temporary font upload (auto-cleanup)
POST /api/upload?mode=admin	Permanent font upload (requires API key)

Font name supports fuzzy matching: exact → prefix → contains.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                        Use Cases                              │
│  Posters/H5  ·  Brand Sites  ·  Blogs  ·  Mini Apps  ·  AI  │
└──────────────────────────┬───────────────────────────────────┘
                           │
              ┌────────────┴────────────┐
              │   AI Chinese Font Skill │ ← Chinese font application
              │   + AI Skill Prompt     │ ← Chinese font application
              └────────────┬────────────┘
                           │
              ┌────────────┴────────────┐
              │   Runtime Font Delivery │ ← On-demand subsetting + incremental loading
              │   SDK + API             │
              └────────────┬────────────┘
                           │
              ┌────────────┴────────────┐
              │   Subset Engine         │ ← fonteditor-core
              │   parse → subset →      │   Font parsing, subsetting, format conversion
              │   optimize → serialize  │
              └─────────────────────────┘

Project Structure

web-font/
├── backend/            # Server: HTTP API + font subsetting engine
│   ├── routes/         # API route handlers
│   ├── font_util/      # Font subsetting core
│   └── server/         # HTTP server (Node.js + LLRT dual runtime)
├── src/                # Frontend: Vue 3 SPA
├── public/
│   └── webfont-sdk.js  # Runtime Font Delivery SDK
├── skills/             # AI Chinese Font Skill
├── examples/           # Before/After demo pages
└── vendor/             # fonteditor-core

Acknowledgments

• kekee000/fonteditor-core — Font parsing, subsetting, and format conversion
• 字体天下 — Free commercial-use Chinese fonts
• Featured in 阮一峰科技爱好者周刊第 100 期

License

MIT © 崮生