一天一个开源项目

开源项目第192期：shadcn-admin — Vite + shadcn/ui 构建的后台管理界面参考集，10+ 页面、RTL 支持、无障碍优先，不是模板，是可复用的 UI 参考库

satnaing 开源的后台管理 UI 参考集，基于 shadcn/ui + Vite + TanStack Router 构建。包含 Dashboard、Tasks、Users、Chats、Apps、Settings、Help Center 等 10+ 页面，全局搜索命令、亮暗模式、RTL 布局支持、Clerk 认证集成。定位是 UI 参考集合而非开箱即用脚手架，Radix UI 底层保证无障碍访问。不依赖 Next.js，纯 Vite 构建，性能更轻。13.9k Stars，MIT。

·约 7 分钟阅读·Frontend
open-sourceshadcn-uiadmin-dashboardViteTanStack-RouterTypeScriptTailwindRadix-UIRTLClerkUItemplate

引言

"每次做项目都要重新搭后台 UI，干脆把这些页面整理成一个可复用的参考集。"

这是「每日一个开源项目」系列的第 192 篇。今天的项目是 shadcn-admin —— satnaing 开源的后台管理界面参考集，基于 shadcn/ui + Vite + TanStack Router 构建。

13,900 颗 Star，MIT 许可。

先说清楚定位：README 里明确写着"This is not a starter project (template) though."——这不是一个开箱即用的脚手架，而是一套 UI 参考集合，展示如何用 shadcn/ui 组合出常见的后台管理界面。你可以直接 clone 来看效果、借鉴结构、复用组件，但它没有配好后端接口、没有业务逻辑，不能直接当项目模板用。

这个定位反而让它更有价值：干净、专注 UI、没有业务耦合。

你会学到什么

  • 为什么选 Vite + TanStack Router 而不是 Next.js
  • shadcn/ui 的底层逻辑：为什么它不是"组件库"
  • 项目包含的 10+ 页面和核心组件
  • RTL 支持的实现方式
  • 与 Ant Design / MUI 后台模板的差异

前提知识

  • 了解 React 基础
  • 用过 Tailwind CSS
  • 知道 shadcn/ui 是什么（或愿意了解）

先理解 shadcn/ui

shadcn/ui 经常被误解为"一个组件库"，安装后 import 使用。它不是。

shadcn/ui 的模式是：把组件源码直接复制到你的项目里。

npx shadcn@latest add button
# 执行后，Button 组件的完整源码出现在你的 src/components/ui/button.tsx
# 这个文件完全属于你，可以随意修改

底层是 Radix UI（提供无障碍交互逻辑）+ Tailwind CSS（提供样式）。你拿到的是可以直接编辑的源代码，不是封装好的黑盒。

这个模式的直接结果：样式完全可控，无障碍访问开箱即有，Bundle 里只有你实际用到的组件。

shadcn-admin 建立在这个基础上，因此整个项目的组件层都是透明可改的。

为什么是 Vite 而不是 Next.js

绝大多数后台管理模板用 Next.js。shadcn-admin 选择了 Vite + TanStack Router，理由很直接：

后台管理系统通常不需要 SSR。

大多数内部工具、管理后台都是需要登录才能访问的 SPA——没有 SEO 需求，没有首屏 SSR 加速的收益，反而带着 Next.js 的服务端复杂性（API Routes、Server Components、服务器部署需求）。

Vite 构建的纯前端 SPA：

  • 构建速度快（HMR 毫秒级）
  • 部署简单（静态文件，Netlify/Vercel/CDN 都行）
  • 没有 Node.js 服务器依赖
  • Bundle 更小

TanStack Router（前身是 React Router v6 的增强版）提供了类型安全的路由，在 TypeScript 项目里比 Next.js App Router 的文件路由更易控制。

页面结构

已认证路由（登录后可访问）

页面内容
Dashboard数据概览，统计卡片，图表，近期活动
Tasks任务列表，过滤、排序、状态管理，DataTable 组件展示
Users用户管理，搜索、分页、角色列表
Chats即时消息界面，对话列表 + 聊天区
Apps应用/集成管理页
Settings多 Tab 设置：账户、通知、外观、显示、安全、快捷键
Help Center帮助文档/FAQ 页

认证页面

  • 登录（Sign In）
  • 注册（Sign Up）
  • 忘记密码（Forgot Password）
  • OTP 验证
  • 另有 Clerk 认证集成版本（/clerk 路由下）

错误页面

  • 401 未授权
  • 403 禁止访问
  • 404 页面不存在
  • 500 服务器错误
  • 503 服务不可用

核心组件

侧边栏导航

使用 shadcn/ui 内置的 Sidebar 组件，可折叠，支持嵌套菜单，配合顶部 Header 构成完整的页面框架。

全局搜索（Command）

Cmd+K（macOS）/ Ctrl+K 呼出全局搜索命令面板，基于 shadcn/ui 的 <Command> 组件，支持键盘导航。这是后台系统里高频但经常被忽视的功能。

DataTable

基于 TanStack Table（前身 React Table）封装的数据表格：

  • 列排序
  • 多条件过滤
  • 分页控制
  • 行选择
  • 列显示/隐藏切换

Tasks 和 Users 页面都用这个组件，是后台开发最常用的复杂组件之一。

主题切换

亮色/暗色模式切换，使用 CSS 变量驱动，shadcn/ui 的标准方案。

RTL 支持

这是 shadcn-admin 区别于大多数同类项目的功能——对阿拉伯语、希伯来语、波斯语等从右到左书写语言的完整支持。

实现方式不是简单地加一个 dir="rtl" 属性，而是对多个 shadcn/ui 组件进行了针对性的定制修改：

专项 RTL 改造的组件： alert-dialog、calendar、command、dialog、dropdown-menu、select、table、sheet、sidebar、switch

这些组件在 RTL 模式下有方向性的 UI 元素（图标位置、下拉方向、动画方向等），需要单独处理。

注意：如果后续用 npx shadcn add 更新这些组件，会覆盖 RTL 改动，需要手动合并。

安装和使用

git clone https://github.com/satnaing/shadcn-admin.git
cd shadcn-admin
pnpm install
pnpm run dev

Clerk 认证集成需要配置环境变量：

cp .env.example .env
# 填入 Clerk 的 PUBLISHABLE_KEY 和 SECRET_KEY

不用 Clerk 的话，项目里有不依赖 Clerk 的认证页面版本（/sign-in、/sign-up 等），直接用就行。

shadcn-admin vs 常见后台模板

维度shadcn-adminAnt Design ProAdminLTE
UI 基础Radix UI + Tailwind（无样式组件）Ant Design（重样式）Bootstrap
构建工具ViteUmi.jsWebpack
路由TanStack RouterUmi 路由无（jQuery 时代）
RTL深度支持基础支持有限支持
无障碍Radix UI 原生保证部分支持基础
定制自由度极高（组件源码在你项目里）受限（import 黑盒）受限
TypeScript完整支持完整支持无
定位UI 参考集合生产脚手架生产模板
Stars13.9k37k+11k+

项目地址与资源

总结

shadcn-admin 的价值在于它的定位选择：不做脚手架，做参考集。

大多数后台模板追求开箱即用，代价是耦合了大量你不需要的东西——认证方案、状态管理、API 层、权限系统……一旦你的需求和模板的预设不同，改造成本比从零开始还高。

shadcn-admin 只给你 UI 层——精心实现的界面结构、组件组合方式、响应式布局，以及 RTL 等细节处理。业务逻辑自己决定怎么加。

Vite + TanStack Router 的技术选型让它比 Next.js 模板更轻，适合后台管理这类 SEO 不重要、部署简单优先的场景。shadcn/ui 的"源码归你"模式保证了定制自由度。

13,900 Stars 说明这个方向是对的：开发者要的不是又一个捆绑了一切的后台框架，而是一套干净的 UI 参考，自己决定怎么组合。

探索 PrimeSkills —— 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。

← 返回博客列表