lhx-kit

🧰 A monorepo-grade toolchain that scaffolds real-world MPA projects. Not "hello world + Vite" — a project that ships with routing, state, request, Mock, CI, Docker, offline packaging, AI-powered issue triage and everything else your team actually needs on day one.

📖 Documentation · 🛠️ Full walkthrough · 🇨🇳 中文 · ⭐ GitHub

---

✨ Why lhx-kit

Pain point	lhx-kit's answer
🔀 webpack.config + package.json scripts + routes.json out of sync	Single project.config.ts drives CLI + Vite plugin + offline + runtime
🐘 React-dom is 192 KB — "just split it"	Physical impossibility + data to prove it. Instead: family grouping + 10KB minChunkSize + CDN externalization
📱 Mobile adaptation is copy-paste hell	setupMobile({maxWidth: 750}) + postcss-pxtorem + desktop centering guard
📦 Hybrid App offline packaging has no standard	lhx-cli offline build → manifest.json + sha256 + brotli + inspect
🧪 Setting up ESLint/Prettier/Husky/Vitest/Playwright eats a whole day	Scaffolded project gets all of it, plus Docker + CI, on day one
🚀 npm publishing needs long-lived NPM_TOKEN secrets	Trusted Publishing (GitHub OIDC) — zero secrets, every release signed with provenance
🤖 Triaging issues by hand is exhausting	GitHub Models-powered triage / Q&A / summarize — free, no API key
👀 PR review, autofix & doc drafting need expensive SaaS bots	Built-in tri-model PR review (GPT-4o + Llama 3.3 + DeepSeek V3) · @bot-fix-lint autofix · @ai-bot fix gated code-fix · @ai-docs doc assistant — all on free GitHub Models
🧩 Scaffolding a new package inside a monorepo is copy-paste-hell	lhx-cli add package <name> auto-detects monorepo root, emits tsup + tsconfig + README skeleton, and is backed by a create-package skill so AI agents can do it too

---

📦 Packages — all published, all Trusted-Publishing signed

Package	Version	Description
@lhx-kit/cli		⚙️ CLI — create / add package / add route
@lhx-kit/config		🧭 SSOT config loader with zod + jiti
@lhx-kit/runtime		🧩 Browser runtime: request / mobile / logger / auth / mock / env / theme / cdn-loader
@lhx-kit/renderer		🎨 JSON-driven UI renderer for Vue 3 + React
@lhx-kit/offline		📦 Offline packaging pipeline: concurrent hashing, brotli, inspect
@lhx-kit/vite-plugin		⚡ Vite plugin: MPA orchestration + CDN + chunk strategy (Rolldown-ready)
@lhx-kit/skills		🧠 Shared skill registry — AI agents & CLI run the same codepaths (create-package, add-route, …)
@lhx-kit/tsconfig		🗂️ Shared TS configs for downstream projects

lhx-kit/
├── apps/
│   └── docs/          📘 Rspress documentation site (publishes to GitHub Pages)
├── examples/
│   ├── vmpa/          🟢 Vue 3 MPA demo (incl. `user-detail` renderer-boundary page)
│   └── rmpa/          🔵 React MPA demo (incl. `user-detail` renderer-boundary page)
├── packages/          📦 8 publishable workspaces (see table above)
├── RENDERER-UPGRADE-PLAN.md  🎨 @lhx-kit/renderer capability boundary + 4-step upgrade roadmap
├── .github/
│   ├── workflows/
│   │   ├── ci.yaml                  ✅ Lint / typecheck / build / cross-platform
│   │   ├── release.yaml             🚀 Changesets + Trusted Publishing
│   │   ├── rspress-docs-ci-cd.yaml  📘 Docs site deploy
│   │   ├── ai-triage.yaml           🤖 New-issue auto labels + welcome
│   │   ├── ai-assistant.yaml        💬 @ai-bot Q&A on any issue
│   │   ├── ai-summarize.yaml        🏷️ Label-triggered TL;DR
│   │   ├── ai-review-gpt.yaml       👀 PR review — GPT-4o (correctness + security)
│   │   ├── ai-review-llama.yaml     👀 PR review — Llama 3.3 70B (architecture + docs)
│   │   ├── ai-review-deepseek.yaml  👀 PR review — DeepSeek V3 (reasoning + edge cases)
│   │   ├── ai-autofix.yaml          🔧 @bot-fix-lint → Biome fix, deterministic (no LLM)
│   │   ├── ai-code-fix.yaml         🛠️ @ai-bot fix → gated AI patch → self-check → Draft PR
│   │   └── ai-docs-assistant.yaml   📝 @ai-docs draft/polish — README & docs helper
│   └── SETUP.md                     📋 One-time repo setup checklist
├── .husky/             🐕 pre-commit / commit-msg / pre-push hooks (biome + typecheck)
├── .vscode/            🪄 Recommended workspace settings
├── biome.json          🎨 Unified lint + format + organize imports
├── commitlint.config   📝 Conventional Commits + scoped (engineering / ai / ...)
├── Makefile            🧰 Command aggregator
└── pnpm-workspace.yaml 📦 `packages/*` + `apps/*` + `examples/*`

---

🚀 Quick start (3 minutes)

# 1. Clone + setup
git clone git@github.com:juwenzhang/lhx-kit.git
cd lhx-kit
make setup                       # pnpm install + pnpm -r build

# 2. Create a new project (outside the repo)
pnpm exec lhx-cli create my-app
cd my-app && pnpm dev

# 3. Or explore the existing demos
make dev-vmpa                    # Vue 3 MPA on :4173
make dev-rmpa                    # React MPA on :4174
make docs-dev                    # Documentation site

# 4. Add a new package inside this monorepo
pnpm exec lhx-cli add package my-utility   # auto-detects monorepo root,
                                           # scaffolds tsup + tsconfig + README
                                           # (CLI + create-package skill share the same codepath)

Requires Node.js >= 18.18.0 and pnpm >= 9.

---

🏗️ How the sausage is made — engineering highlights

This repo is not just a scaffold; it's a real-world reference project for how to run a polished open-source JS monorepo in 2026:

📦 Release pipeline — zero-secret, provenance-signed

• Changesets governs per-package versioning with a fixed group that keeps all @lhx-kit/* in lock-step
• npm Trusted Publishing (OIDC) — no NPM_TOKEN secret; GitHub issues a short-lived publish credential per release, and every published tarball carries a sigstore-backed provenance attestation
• Read the full playbook: Release pipeline: Changesets + Trusted Publishing

⚙️ CI strategy — paths allow-list, cross-platform lockfile, frozen install

• paths allow-list on every workflow → docs-only pushes skip CI entirely
• pnpm.supportedArchitectures declares Linux/macOS/Windows + glibc/musl → lockfile stores every platform's native binaries → no more Cannot find module @rollup/rollup-win32-x64-msvc on Windows runners
• --frozen-lockfile is universal; pre-push hook runs biome + typecheck locally so CI is strictly a safety net
• Read the full playbook: CI strategy

🤖 AI automation — free (GitHub Models), zero API keys

Eight workflows, all backed by actions/ai-inference@v1 + permissions: models: read, no external API keys, no paid SaaS:

Issue lifecycle

• ai-triage — every new issue gets auto-labeled (up to 5), optionally marked needs-reproduction, and welcomed in the issue's own language
• ai-assistant — comment @ai-bot <question> on any issue/PR; the bot reads README + issue context + last 5 comments and replies with grounded answers
• ai-summarize — label an issue ai-summary and get a structured TL;DR (key points / decisions / open questions / next step)

PR lifecycle

• ai-review-gpt — GPT-4o focuses on correctness, security, breaking changes
• ai-review-llama — Meta Llama 3.3 70B focuses on architecture, docs, naming consistency
• ai-review-deepseek — DeepSeek V3 focuses on edge cases, reasoning chains, test coverage — three independent voices across OpenAI / Meta / DeepSeek training pipelines
• ai-autofix — comment @bot-fix-lint on a PR → deterministic biome check --write, no LLM in the loop (safe, predictable)
• ai-code-fix — comment @ai-bot fix <hint> → 4-layer gating (actor perm + file allow-list + diff size cap + human label) → AI patch → self-check (typecheck+lint+test) → one auto-iteration on failure → opens a Draft PR (never pushes to main)

Docs workflow

• ai-docs-assistant — @ai-docs draft <topic> scaffolds a new MD stub; @ai-docs polish <path> rewrites an existing doc in place — both open Draft PRs

All eight carry signature markers to prevent bot-loop-back. Read the full playbook: GitHub AI automation (zero-cost) · AI review strategy

🎨 Tooling

Concern	Tool	Notes
Lint / format / organize imports	🎨 Biome	Single binary, ~100× faster than ESLint+Prettier
Commit messages	📝 commitlint	Conventional Commits with a 16-scope enum (cli/runtime/ai/…)
Git hooks	🐕 Husky	pre-commit → lint-staged; commit-msg → commitlint; pre-push → biome + typecheck
Testing	🧪 Vitest + Playwright	Per-package units + cross-browser e2e
CI matrix	🏗️ GitHub Actions	Node 20/22 on Ubuntu + cross-platform job on Linux/macOS/Windows
Docs	📘 Rspress	Auto-deploys to GitHub Pages on apps/docs/** push

---

📖 Documentation

👉 https://juwenzhang.github.io/lhx-kit/

Top reads

• 🚀 Getting started — 10 min to running
• 🛠️ Project walkthrough — from zero to a published package, end to end
• 🧠 Architecture overview — 8-package layered design
• ⚡ Performance decisions — why we don't split react-dom
• 🌐 CDN externalization — the full Preact fallback saga
• 📱 Mobile adaptation — lib-flexible + desktop guard

Deep dives by topic

• 🛠️ Engineering column — Release pipeline · CI strategy · AI automation · (coming) Commit/PR conventions
• 📦 Offline packaging deep-dive — compression libs, hashing, algorithms
• 🧩 Vite plugin internals — manifest-driven chunk grouping
• 🔥 Rolldown migration post-mortem — how Vite 8 broke our generateBundle
• 🎨 Renderer upgrade plan — @lhx-kit/renderer capability boundary, gap-by-gap audit (state / events / AOP / route / lifecycle / error-boundary) backed by a real React+Vue demo at examples/{rmpa,vmpa}/src/pages/user-detail/, plus a 4-step landing roadmap

---

🧰 Development

make help               # List all available commands

# Quality
make lint               # Biome check
make lint-fix           # Auto-fix
make typecheck          # tsc --noEmit across workspaces
make test               # All unit tests
make check              # lint + typecheck + test (CI bundle)

# Build
make build              # Build every workspace
make build-packages     # Only internal packages
make docs-build         # Build the docs site

# Docs maintenance
make sync-readmes       # Regenerate the managed footer inside every @lhx-kit/* README (idempotent)

# Clean
make clean              # Remove dist/doc_build caches
make reset              # Nuke node_modules + lockfile

Full Makefile target list: make help.

---

🤝 Contributing

PRs are welcome! Please read CONTRIBUTING.md for:

• Local dev setup
• Commit message format (Conventional Commits, <type>(<scope>): <subject>)
• PR checklist
• How to write a changeset (pnpm changeset) when your change is user-facing

Your first PR? Great issues to start from are labeled good first issue and help wanted.

Got a question? Open an issue — the AI triage bot will tag it and a maintainer will follow up. Or drop @ai-bot <your question> on any existing issue for an instant answer grounded in the README and current thread.

By participating you agree to abide by the Code of Conduct.

---

🛡️ Security

Please do not open public issues for security problems. See SECURITY.md for private reporting.

Every published package carries a provenance attestation — you can verify that a given tarball was built by this exact repo at a specific commit by checking the package page on npmjs.com.

---

📄 License

MIT © luhanxin

---

Built with ❤️ in China · Made for real products, not demos