create-hh-admin

English | 简体中文

Create Vue 3 admin projects from maintained Hh Admin templates.

create-hh-admin is the npm create CLI for Hh Admin Starter. It scaffolds internal tools, SaaS back offices, management dashboards, qiankun micro-frontend child apps, and qiankun host shells with Vue 3, Vite, TypeScript, Arco Design, Pinia, Vue Router, Axios, optional mock APIs, and reusable Hh Admin components.

• Online demo: https://doc.huangbin.shop
• Source repository: https://gitee.com/357177179/hh-admin
• Templates: simple, full, qiankun, qiankun-host, qiankun-platform

Why Use It

• Start with a ready admin shell instead of wiring login, layout, routes, stores, and request utilities from scratch.
• Choose a focused business starter, a larger reference demo, or a qiankun-ready micro-frontend template.
• Use shared components such as HhTable, HhForm, HhPageLayout, HhUpload, HhEditor, and HhTreePanel.
• Keep generated project metadata for future upgrade and migration tooling.

Quick Start

npm create hh-admin@latest
npm create hh-admin@latest my-admin

Then run the generated app:

cd my-admin
pnpm install
pnpm dev

If you omit the project name, the CLI will ask for it interactively and use hh-admin-app as the default.

Supported templates are full, simple, qiankun, qiankun-host, and qiankun-platform. Supported package managers are pnpm, npm, and yarn; qiankun-platform currently requires --pm pnpm.

Choose A Template

| Template | Best for | Includes | | --- | --- | --- | | simple | New business systems and clean internal tools | Core admin shell, login, system pages, stores, routes, API wrapper, common components, optional mock API | | full | Learning from a larger reference app or building from the full demo | The larger Gi Admin Pro-derived surface, examples, documentation pages, and component usage | | qiankun | Micro-frontend apps that must also run standalone | The simple foundation plus qiankun lifecycle, public-path handling, and validation scripts | | qiankun-host | Platform shells that will mount one or more qiankun child apps | Thin main app shell, menu, child app container, qiankun loading, and host wiring notes | | qiankun-platform | New platforms that will grow into multiple qiankun child apps | pnpm workspace with host, apps/admin, and packages/shared contracts |

Usage

npm create hh-admin@latest my-admin
pnpm create hh-admin@latest
pnpm create hh-admin@latest my-admin
npx create-hh-admin@latest my-admin

Pass CLI options like this:

npm create hh-admin@latest my-admin -- --template simple --pm pnpm --mock
pnpm create hh-admin@latest my-admin --template simple --pm pnpm --mock
npx create-hh-admin@latest my-admin --template simple --pm pnpm --mock

npm create needs -- before CLI options so npm forwards them to create-hh-admin.

Templates

• simple: default business starter with login, layout, router guards, stores, system pages, API wrapper, common components, and optional mock API.
• full: reference-rich demo template with the larger admin surface retained.
• qiankun: based on simple, with standalone development and qiankun micro-frontend lifecycle support.
• qiankun-host: thin qiankun main app shell for platform navigation and mounting child apps.
• qiankun-platform: pnpm workspace with a host shell, an admin child app, and shared host/child contracts.

Create from a specific template:

npm create hh-admin@latest my-admin -- --template simple
npm create hh-admin@latest my-full-admin -- --template full
npm create hh-admin@latest my-micro-admin -- --template qiankun
npm create hh-admin@latest my-platform -- --template qiankun-host
npm create hh-admin@latest my-platform -- --template qiankun-platform --pm pnpm

Options

• --template <full|simple|qiankun|qiankun-host|qiankun-platform> selects the project template.
• --app-title <title> sets the generated app title shown on the login page and footer. Defaults to Hh.
• --pm <pnpm|npm|yarn> selects the package manager shown in next-step instructions and used by --install.
• --install / --no-install controls dependency installation after project creation.
• --git / --no-git controls git initialization.
• --mock / --no-mock toggles generated mock API support. --mock keeps mock files, sets VITE_MOCK_ENABLED = 'true', and uses /mock as the API prefix. --no-mock removes mock files, sets VITE_MOCK_ENABLED = 'false', and uses /api as the backend proxy prefix.
• --force overwrites the target directory when it is not empty.
• --yes accepts defaults for omitted options and skips interactive prompts.
• --json emits JSON for supported commands and errors. It is intended for scripts and automation.
• doctor --help shows diagnostics help.
• doctor --json emits a stable JSON health result.
• upgrade --help explains the read-only upgrade check.
• upgrade --compare prints read-only manual review hints for generated project files.
• upgrade --json emits a stable JSON read-only upgrade diagnostic.
• update --help explains the safe dependency update command.
• update --backup creates package.json.create-hh-admin.bak before writing package.json changes.
• update --check exits with code 1 when safe dependency updates are needed.
• update --dry-run shows whitelisted package changes without writing files.
• update --interactive shows available safe dependency updates, write scope, and lets you choose which ones to write.
• update --json emits a stable JSON update result.

Project names, template names, and package manager names are validated before files are copied. If the target directory already exists and contains files, the CLI stops with a clear error unless --force is passed.

Use --force only when the existing target directory can be replaced:

npx create-hh-admin@latest my-admin --template simple --pm pnpm --force

Use --yes when running non-interactively:

npx create-hh-admin@latest my-admin --yes
npx create-hh-admin@latest my-admin --yes --app-title "Acme Admin"
npx create-hh-admin@latest my-admin --yes --template qiankun --pm pnpm --no-install --no-git

Generated Project

npm create hh-admin@latest my-admin -- --template simple --pm pnpm --mock
cd my-admin
pnpm install
pnpm dev

Generated projects include an hhAdmin metadata block in package.json with the template name and template version. The upgrade and update commands use this metadata when run inside an existing generated project.

Environment And Mock API

Generated projects include environment files for development, production, and test builds:

.env.development
.env.production
.env.test

The qiankun template also includes .env.qiankun for micro-app integration builds.

Important variables:

| Variable | Purpose | | --- | --- | | VITE_MOCK_ENABLED | Enables or disables built-in mock route registration. | | VITE_API_PREFIX | Axios base URL. Use /mock for built-in mock routes or /api for a backend proxy. | | VITE_API_BASE_URL | Backend target used by the dev-server /api proxy. | | VITE_BASE | Vite public base path for deployed assets. |

Use --mock for a self-contained demo or first run. Use --no-mock when the generated project should point at a real backend from the start.

Updating Projects

Use the latest CLI for new projects:

npm create hh-admin@latest my-admin
pnpm create hh-admin@latest my-admin
npx create-hh-admin@latest my-admin

Generated projects are normal user-owned applications after creation. Template files are not overwritten automatically, because users may have changed components, routes, pages, and config files.

The update model is:

• create-hh-admin creates projects and runs maintenance commands.
• upgrade is read-only. It checks metadata and optional high-signal template integration points.
• update safely writes package.json changes for a small whitelist of template-managed dependencies.
• @hh-admin/core contains shared runtime utilities such as request helpers, hooks, permissions, stores, and layout logic.
• @hh-admin/components contains reusable components such as HhTable, HhForm, HhPageLayout, HhUpload, HhEditor, and common cells.
• Templates contain project structure, examples, routes, views, and integration code.

To preview safe dependency updates:

npx create-hh-admin@latest update --check
npx create-hh-admin@latest update --dry-run
npx create-hh-admin@latest update --json

To apply safe dependency updates:

npx create-hh-admin@latest update
npx create-hh-admin@latest update --backup
npx create-hh-admin@latest update --interactive
pnpm install

The first version of update only compares the generated project's package.json against the current CLI's built-in template package.json, then updates whitelisted dependencies. The whitelist currently includes @hh-admin/components and @hh-admin/core. Use --check in CI to fail when those dependencies drift. Use --dry-run to preview exact package.json version changes. Use --backup to create package.json.create-hh-admin.bak before a real write. Use --interactive to see available updates, write scope, and select one or more safe dependency updates before package.json is written.

update does not run install automatically. It does not overwrite template files, edit vite.config.ts, or change user business code.

When a release changes generated project structure or config files, use:

npx create-hh-admin@latest upgrade
npx create-hh-admin@latest upgrade --compare
npx create-hh-admin@latest upgrade --json

The upgrade command is read-only. It uses the generated project's hhAdmin.template and hhAdmin.templateVersion metadata to compare the project with the latest create CLI, then suggests whether manual upgrade notes in docs/UPGRADE.md should be reviewed. It does not modify project files.

Use --compare for a read-only checklist of generated-project files:

npx create-hh-admin@latest upgrade --compare
npx create-hh-admin@latest upgrade --compare --json

The compare check does not calculate a full source diff and does not modify files. It checks high-signal template integration points such as generated README and AGENTS guidance, key package versions, HTTP API prefix wiring, .env* mock/API variables, vite.config.ts mock switching, and qiankun scripts/env files when the project uses the qiankun template.

When a check needs attention, text output lists review or missing items first, shows the failed sub-checks, then summarizes the checks that passed. JSON output includes CI-friendly compare.hasChanges, compare.totals, compare.files, compare.items[].severity, and compare.items[].checks[] fields for scripts that need machine-readable detail.

qiankun

The qiankun template supports normal standalone development with pnpm dev.

npm create hh-admin@latest micro-admin -- --template qiankun --pm pnpm --mock
cd micro-admin
pnpm install
pnpm dev

For qiankun 2.x validation, use pnpm dev:qiankun. This builds a stable IIFE bundle and serves it from dist, avoiding Vite dev HTML module-script incompatibilities in qiankun 2.x hosts.

The local micro-app assets are:

http://localhost:7101/assets/hh-admin-qiankun.js
http://localhost:7101/assets/hh-admin-qiankun.css

Create a qiankun main app shell with:

npm create hh-admin@latest host -- --template qiankun-host --pm pnpm

For a multi-app platform, keep the host light and create business child apps separately:

npm create hh-admin@latest apps/admin -- --template qiankun --pm pnpm --mock
npm create hh-admin@latest apps/crm -- --template qiankun --pm pnpm --mock

Doctor

Run doctor to inspect the local CLI environment and, when executed inside a generated Hh Admin project, the project template metadata.

npx create-hh-admin@latest doctor
npx create-hh-admin@latest doctor --json

The check reports:

• Node.js version.
• Detected package manager.
• Installed CLI version and npm latest version.
• Official npm registry used for the latest-version lookup.
• Available templates.
• Current project hhAdmin.template and hhAdmin.templateVersion, when available.
• Suggestions for next steps, such as using the latest CLI for new projects or reviewing docs/UPGRADE.md for existing projects.

JSON output uses the same stable envelope as create commands:

npx create-hh-admin@latest doctor --json

Upgrade Check

Run upgrade inside a generated Hh Admin project to check whether the project template metadata is aligned with the latest create CLI.

npx create-hh-admin@latest upgrade
npx create-hh-admin@latest upgrade --compare
npx create-hh-admin@latest upgrade --json

This command is read-only. It reports:

• Project name, template, and template version.
• Current CLI version and npm latest version.
• Whether the project is current, outdated, or unknown.
• Suggestions for next steps. When a project is outdated, review docs/UPGRADE.md before changing existing files.

upgrade --help documents the read-only behavior and status meanings. The command never modifies project files.

upgrade --compare adds manual review hints for:

• package.json template metadata.
• Generated README env/mock/API guidance.
• AGENTS.md command, mock/API, and agent behavior guidance.
• Key template package versions such as @hh-admin/components, @hh-admin/core, vue, vite, and @arco-design/web-vue.
• src/utils/http.ts API prefix wiring.
• .env.development, .env.production, and .env.test.
• vite.config.ts mock switch behavior.
• qiankun scripts and .env.qiankun for qiankun projects.

Items that need attention are printed before passing items. In JSON mode, each item includes structured checks so automation can tell which snippet, file, or script is missing.

JSON Output

Commands using --json emit a stable JSON envelope:

{
  "ok": true,
  "data": {},
  "error": null
}

Create commands return the generated project summary:

npx create-hh-admin@latest my-admin --yes --json

{
  "ok": true,
  "data": {
    "projectName": "my-admin",
    "packageName": "my-admin",
    "targetDir": "/path/to/my-admin",
    "template": "simple",
    "templateVersion": "0.1.13",
    "appTitle": "Hh",
    "packageManager": "pnpm",
    "mock": true,
    "install": false,
    "git": false,
    "nextSteps": [
      "cd my-admin",
      "pnpm install",
      "pnpm dev"
    ]
  },
  "error": null
}

Errors include a stable code, a human-readable message, optional suggestions, and diagnostic details that do not include credentials:

{
  "ok": false,
  "data": null,
  "error": {
    "code": "UNKNOWN_TEMPLATE",
    "message": "Unknown template: nope. Available templates: full, simple, qiankun, qiankun-host, qiankun-platform",
    "suggestions": [
      "Choose one of: full, simple, qiankun, qiankun-host, qiankun-platform."
    ],
    "details": {
      "template": "nope",
      "availableTemplates": [
        "full",
        "simple",
        "qiankun",
        "qiankun-host",
        "qiankun-platform"
      ]
    }
  }
}

Publish Check

Before publishing this package, run:

pnpm build
pnpm validate
pnpm test:create
pnpm tarball:smoke:create
pnpm release:prep <version>
pnpm release:create <version>
pnpm registry:smoke:post-release

Use the root pnpm tarball:smoke:create script before publishing to pack this package and generate simple, full, and qiankun projects from the packed tarball. Use pnpm release:prep <version> after the version and release note are ready; it syncs the checked-in example projects to the target template version and commits only when release-prep files have real changes, so reruns are safe. Use pnpm release:create <version> for the guarded publish flow. It avoids workspace argument forwarding issues in pnpm publish and always targets the official npm registry instead of a local mirror. After publishing, use pnpm registry:smoke:post-release to create a real project from create-hh-admin@latest and verify upgrade --compare --json plus update --backup --json against the published package.

Attribution

The templates include code derived from Gi Admin Pro by Lin, licensed under Apache License 2.0. See the generated project's LICENSE.

create-hh-admin 简体中文

English | 简体中文

从维护中的 Hh Admin 模板快速创建 Vue 3 后台管理项目。

create-hh-admin 是 Hh Admin Starter 的 npm create CLI，适合创建内部系统、SaaS 后台、管理面板和 qiankun 微前端应用。模板内置 Vue 3、Vite、TypeScript、Arco Design、Pinia、Vue Router、Axios、可选 mock API，以及可复用的 Hh Admin 组件。

• 在线预览：https://doc.huangbin.shop
• 源码仓库：https://gitee.com/357177179/hh-admin
• 支持模板：simple、full、qiankun

为什么使用

• 开箱即用的后台框架，包含登录、布局、路由、状态管理和请求工具。
• 可选择轻量业务模板、完整参考模板、qiankun 子应用模板或 qiankun 主应用模板。
• 内置共享组件，例如 HhTable、HhForm、HhPageLayout、HhUpload、HhEditor 和 HhTreePanel。
• 生成项目会记录模板元信息，便于未来升级和迁移工具识别。

快速开始

npm create hh-admin@latest
npm create hh-admin@latest my-admin

运行生成后的项目：

cd my-admin
pnpm install
pnpm dev

如果省略项目名，CLI 会进入交互式提问，并默认使用 hh-admin-app。

选择模板

| 模板 | 适合场景 | 包含内容 | | --- | --- | --- | | simple | 新业务系统、清爽的内部工具 | 后台基础框架、登录、系统页面、状态管理、路由、API 封装、常用组件、可选 mock API | | full | 参考完整示例或基于完整演示继续开发 | 更完整的 Gi Admin Pro 衍生页面、示例、文档页和组件用法 | | qiankun | 需要独立运行并接入 qiankun 的微前端应用 | simple 基础能力、qiankun 生命周期、public path 处理和验证脚本 | | qiankun-host | 需要挂载多个 qiankun 子应用的平台壳子 | 轻量主应用、菜单、子应用容器、qiankun 加载和接线说明 | | qiankun-platform | 准备长期扩展多个 qiankun 子应用的平台工程 | pnpm workspace，内置 host、apps/admin 和 packages/shared 协议包 |

常用命令

npm create hh-admin@latest my-admin
pnpm create hh-admin@latest my-admin
npx create-hh-admin@latest my-admin

传递 CLI 参数：

npm create hh-admin@latest my-admin -- --template simple --pm pnpm --mock
pnpm create hh-admin@latest my-admin --template simple --pm pnpm --mock
npx create-hh-admin@latest my-admin --template simple --pm pnpm --mock

npm create 需要使用 --，这样 npm 才会把后面的参数转发给 create-hh-admin。

参数

• --template <full|simple|qiankun|qiankun-host|qiankun-platform> 选择项目模板。
• --app-title <title> 设置登录页和页脚展示的应用名称，默认是 Hh。
• --pm <pnpm|npm|yarn> 设置包管理器提示，并用于 --install。
• --install / --no-install 控制创建后是否安装依赖。
• --git / --no-git 控制是否初始化 git 仓库。
• --mock / --no-mock 控制是否生成 mock API 支持和对应环境配置。--mock 会保留 mock 文件，设置 VITE_MOCK_ENABLED = 'true'，并使用 /mock 作为接口前缀；--no-mock 会移除 mock 文件，设置 VITE_MOCK_ENABLED = 'false'，并使用 /api 作为后端代理前缀。
• --force 允许覆盖非空目标目录。
• --yes 使用默认值并跳过交互式提问。
• --json 输出稳定 JSON，适合脚本集成。
• doctor --help 查看诊断命令帮助。
• doctor --json 输出环境健康检查结果。
• upgrade --help 查看只读升级检查说明。
• upgrade --compare 输出生成项目文件的只读对比建议。
• upgrade --json 输出只读升级诊断结果。

环境变量和 Mock API

生成后的项目包含开发、生产和测试环境配置：

.env.development
.env.production
.env.test

qiankun 模板还会包含 .env.qiankun，用于微前端集成构建。

关键变量：

| 变量 | 用途 | | --- | --- | | VITE_MOCK_ENABLED | 控制是否注册内置 mock 路由。 | | VITE_API_PREFIX | Axios 基础路径。内置 mock 使用 /mock，真实后端代理使用 /api。 | | VITE_API_BASE_URL | 开发服务器 /api 代理到的后端地址。 | | VITE_BASE | Vite 静态资源公共路径。 |

首次体验或演示推荐使用 --mock。如果项目一开始就要接真实后端，使用 --no-mock。

项目诊断

运行 doctor 可以检查本地 CLI 环境；如果在生成后的 Hh Admin 项目目录里执行，还会识别项目模板元信息。

npx create-hh-admin@latest doctor
npx create-hh-admin@latest doctor --json

诊断内容包括：

• Node.js 版本。
• 识别到的包管理器。
• 当前 CLI 版本和 npm latest 版本。
• 查询 latest 使用的官方 npm registry。
• 当前 CLI 可用模板列表。
• 当前项目的 hhAdmin.template 和 hhAdmin.templateVersion。
• 下一步建议，例如新项目使用 latest CLI，已有项目先查看 docs/UPGRADE.md。

升级检查

在生成后的 Hh Admin 项目目录里运行 upgrade，可以检查当前项目模板版本是否和最新 create CLI 对齐。

npx create-hh-admin@latest upgrade
npx create-hh-admin@latest upgrade --compare
npx create-hh-admin@latest upgrade --json

这个命令目前是只读诊断，不会修改项目文件。它会输出：

• 项目名称、模板和模板版本。
• 当前 CLI 版本和 npm latest 版本。
• 当前项目状态：current、outdated 或 unknown。
• 下一步建议。如果项目版本落后，先查看 docs/UPGRADE.md 再手动调整已有项目。

upgrade --help 会说明只读行为和状态含义。该命令不会修改项目文件。

upgrade --compare 会额外输出生成项目关键文件的人工检查建议，包括：

• package.json 模板元信息。
• README 中的 env/mock/API 说明。
• AGENTS.md 中的命令、mock/API 和 Agent 行为说明。
• @hh-admin/components、@hh-admin/core、vue、vite、@arco-design/web-vue 等关键模板依赖版本。
• src/utils/http.ts 的 API 前缀接线。
• .env.development、.env.production、.env.test。
• vite.config.ts 中 mock 开关是否跟随 VITE_MOCK_ENABLED。
• qiankun 项目的 scripts 和 .env.qiankun。

需要处理的项目会优先显示，并列出失败的子检查；JSON 模式下每个 item 会包含结构化 checks，方便脚本判断具体缺少哪个片段、文件或脚本。

qiankun

qiankun 模板支持普通独立开发：

npm create hh-admin@latest micro-admin -- --template qiankun --pm pnpm --mock
cd micro-admin
pnpm install
pnpm dev

如果要验证 qiankun 2.x 接入，可以使用：

pnpm dev:qiankun

这个命令会构建稳定的 IIFE 包并从 dist 提供资源，避免 qiankun 2.x 加载 Vite dev HTML/ESM 入口时的兼容问题。

说明

生成后的项目属于用户自己的应用，模板文件不会自动覆盖。未来升级和迁移工具会基于生成项目 package.json 中的 hhAdmin.template 和 hhAdmin.templateVersion 元信息工作。

模板包含来自 Gi Admin Pro by Lin 的代码，遵循 Apache License 2.0。详见生成项目中的 LICENSE。