110 lines
3.3 KiB
Markdown
110 lines
3.3 KiB
Markdown
# 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` 可查看这些组件的使用示例。
|
||
|
||
## 目录结构
|
||
|
||
```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`。
|