# shadcn-admin-template

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

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

![preview](public/images/shadcn-admin.png)

## 特性

- 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` 可查看这些组件的使用示例。

## 目录结构

```txt
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
```

## 本地开发

安装依赖：

```bash
pnpm install
```

启动开发服务：

```bash
pnpm dev
```

构建生产版本：

```bash
pnpm build
```

检查代码：

```bash
pnpm lint
```

## 环境变量

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

```bash
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`。