shadcn-admin-template

一个开箱即用的 React 管理后台模板，基于 shadcn/ui、Tailwind CSS v4、TanStack Router、TanStack Query 和 Vite 构建。

本模板保留了通用后台常见页面和交互示例，并补充了一组可复用的后台组件样式，用于快速启动新的管理端项目。

特性

• React 19 + Vite 8 + TypeScript
• Tailwind CSS v4 + shadcn/ui + Radix UI
• TanStack Router 文件路由
• TanStack Query 数据请求状态管理
• TanStack Table 示例表格
• Clerk 认证示例
• 明暗主题、RTL、布局模式配置
• Dashboard、Tasks、Users、Apps、Chats、Settings、Errors 等示例页面
• Components 示例页，集中展示后台通用组件和样式 token
• 可直接用于 SPA 部署，已包含 Netlify fallback 配置

新增模板组件

src/components/admin/ 提供了从实际后台项目中抽象出来的通用组件：

• StatusBadge：语义化状态徽章，支持 success、warning、info、danger、neutral
• AdminActionDialog：带状态色、图标、loading 态的确认弹窗
• AdminRowActionsMenu：表格行操作菜单
• BatchOperationsToolbar：批量操作工具栏
• EntityDetailSheet：实体详情抽屉
• SelectableList：带搜索和勾选状态的列表
• EntityRef / ResourcePreview：实体和资源预览展示

对应的状态色 token 和后台布局 class 位于：

• src/styles/theme.css
• src/styles/index.css

进入 /components 可查看这些组件的使用示例。

目录结构

src/
├── assets/          # 图标与静态资源
├── components/      # 通用组件与 shadcn/ui primitive
│   ├── admin/       # 后台业务无关组件
│   ├── data-table/  # 表格组件
│   ├── layout/      # 应用布局
│   └── ui/          # shadcn/ui 组件
├── context/         # 主题、布局、搜索等上下文
├── features/        # 页面级功能模块
├── hooks/           # 通用 hooks
├── lib/             # 工具函数
├── routes/          # TanStack Router 文件路由
├── stores/          # Zustand store
└── styles/          # 全局样式与主题 token

本地开发

安装依赖：

pnpm install

启动开发服务：

pnpm dev

构建生产版本：

pnpm build

检查代码：

pnpm lint

环境变量

复制 .env.example 为 .env.local，按需配置：

VITE_CLERK_PUBLISHABLE_KEY=

如果暂时不用 Clerk，可以保留为空，但 Clerk 相关页面需要有效 key 才能完整运行。

pnpm 构建脚本说明

pnpm-workspace.yaml 中的 allowBuilds 用于批准 @swc/core、esbuild、@clerk/shared 的安装脚本，避免 pnpm v10/v11 在非交互环境中因为未批准 build scripts 而中断安装。

关于配置文件

• netlify.toml：Netlify 部署 SPA 时的 history fallback 配置，保留为可选部署配置。
• knip.config.ts：pnpm knip 使用的未使用代码检查配置，保留。
• components.json：shadcn/ui CLI 配置，保留。
• .prettierrc / eslint.config.js：格式化和 lint 配置，保留。

License

本模板基于 MIT 协议项目衍生，保留原始许可证信息。详见 LICENSE。