Super Admin

简体中文

English

简体中文

English

Appearance

快速开始 ​

这篇指南面向想用 Super Admin 创建自己 admin 项目的用户。如果你要贡献 lineo7387/super-admin 源码仓库，请看后面的源码仓库开发部分。

运行环境 ​

Super Admin 当前要求 Node.js ^20.19.0 || >=22.13.0。这个范围同时写入源码仓库、create-super-admin 包和每个生成项目的 package.json。

在线预览 ​

打开无需后端的完整 Admin Demo。Demo 使用 canonical apps/admin 静态构建和 mock data，不要求数据库、auth provider 或 AI provider；登录信息直接显示在页面中。

Cyberpunk dark profile 下的 Super Admin Users 页面

创建你的 Admin App ​

使用公开 npm starter：

bash
npm create super-admin@latest my-admin
cd my-admin
npm install
npm run dev

更偏好 pnpm：

bash
pnpm dlx create-super-admin@latest my-admin --pm pnpm
cd my-admin
pnpm install
pnpm dev

非交互环境里如果想生成可选 ECharts 案例页：

bash
pnpm dlx create-super-admin@latest my-admin --theme base --charts echarts --pm pnpm

交互式安装会询问是否使用 ECharts；选择后才会安装 echarts、vue-echarts 并在 Examples 下生成适配当前主题的图表案例页面。

显式选择英文默认 locale，并在生成阶段省略全部示例：

bash
pnpm dlx create-super-admin@latest my-admin --theme base --locale en-US --no-examples --pm pnpm
  • --locale zh-CN|en-US 选择默认 locale；不带 --i18n 时只保留所选 catalog。
  • --i18n --locale en-US 保留双语 catalog 与切换器，同时让 en-US 成为默认值。
  • --no-examples 同步裁剪 Examples registration、示例 pages、API adapters、mock data、charts 和对应 AI context；它不能与 --charts echarts 同时使用。

生成出来的项目就是你的应用。它会比这个源码仓库更小，不包含发布自动化、维护者 AI workflow 文件、docs 站点或可选 reference smoke 工具。

默认生成的是 standard 质量模式，包含 ESLint、Vitest、一个代表性的 starter 契约测试，以及完整质量命令：

bash
pnpm lint
pnpm test
pnpm typecheck
pnpm build
pnpm check

pnpm check 会依次执行 lint、test、typecheck 和 production build。如果你明确只要更轻的 typecheck/build 基线，可以使用 --minimal：

bash
pnpm dlx create-super-admin@latest my-admin --theme base --minimal --pm pnpm

Minimal 输出不会残留 ESLint/Vitest config、dependency、script 或 test file。所选模式会记录在 super-admin.config.ts 和生成的 AI context 中。

定制 Starter ​

先看这些位置：

  • src/modules/：feature *.manifest.ts、示例 routes 和 pages；manifest 是 nav、route、route meta 与 permissions 的唯一事实源。
  • src/api/：API adapters，用来归一化 mock 数据或你的 API 响应。
  • src/api/mock/：可替换的 mock 数据源。
  • src/modules/app-module-registry.ts：通用 module registration 校验、排序和默认入口派生。
  • src/modules/examples/examples.manifest.ts：挂载和组合示例 feature manifests。
  • src/modules/examples/examples.registration.ts：Examples 的默认入口和旧路径兼容 redirects。
  • src/modules/module-registry.ts：只组合当前 app 实际启用的 top-level registrations。
  • src/shell/layout-registry.ts：typed layout component/preview registrations；未知 ID 使用 neutral fallback。
  • src/modules/auth/components/auth-recipe-registry.generated.ts：已安装 theme 的 auth recipes；未知 profile 使用 neutral recipe。
  • AGENTS.md 与 ai-context/：当前 quality mode、数据流和真实扩展入口；不要求 AI provider。

默认 starter 不要求：

  • backend server
  • database 或 ORM
  • auth provider
  • AI provider
  • 固定 API response shape
  • release、GitHub、Trellis、Codex 或 Claude workflow tooling

删除 Examples ​

Examples 是一个可整体删除的功能切片，不是 shell、auth 或 workspace 的隐式依赖。完整删除方法见示例指南。 新项目也可以直接使用 --no-examples，让 CLI 在生成阶段执行同一完整裁剪。

删除 Examples registration 后：

  • /dashboard、/workbench、/access、/users* 等示例兼容路径会一起消失，不会留下悬空 redirect。
  • 根路由、登录成功跳转和最后一个 workspace tab 的 fallback 会自动使用第一个剩余 module；默认情况下是 /ui-kit/foundations。
  • 如果继续删除所有 top-level modules，应用会进入中性的 /workspace 页面。

开发源码仓库 ​

只有当你要贡献 lineo7387/super-admin 本身，修改 packages、docs、release scripts 或模板源码时，才需要走这条路径。

前置条件 ​

  • Node.js ^20.19.0 || >=22.13.0。
  • 与 root packageManager 字段匹配的 pnpm。

安装依赖：

bash
pnpm install

运行 admin app：

bash
pnpm dev

运行文档站点：

bash
pnpm docs:dev

构建整个 workspace：

bash
pnpm build

源码仓库地图 ​

  • apps/admin/src/modules/examples/：可复制的示例 routes。
  • apps/admin/src/modules/ui-kit/：shared primitive 展示。
  • apps/admin/src/api/：模块 API adapters。
  • apps/admin/src/api/mock/：mock API 数据源。
  • packages/ui/：共享 admin UI primitives。
  • packages/core/：共享 frontend contracts。
  • packages/theme/：内置 design profiles 和 token helpers。

源码仓库边界 ​

源码仓库包含用于开发和发布 Super Admin 的维护者材料。这些材料必须留在生成项目之外，也不是你在自己 app 中使用 Super Admin 的必需条件。

create-super-admin 生成的项目仍应避免强制要求：

  • backend server
  • database 或 ORM
  • auth provider
  • AI provider
  • 固定 API response shape
  • CLI generation 或 release tooling

这些能力可以后续按需添加，但不应成为运行或定制前端模板的前提。