Shadcn Vue Admin

简体中文 | English

A frontend UI template built with shadcn-vue, Vue 3 and Vite, bringing together common layouts, components and example pages that you can customize and extend. Adapted from shadcn-admin for Vue.

Live Demo

This repository provides frontend examples. Login is mocked, and pages such as Tasks use local sample data. Connect your own authentication and business APIs before using it in production.

✨ Key Features

• ✅ Light, dark and system appearance, with persistent theme settings
• ✅ Global search command palette
• ✅ Sidebar navigation built with shadcn-vue components
• ✅ Example pages for dashboards, tasks, users, settings, authentication and errors
• ✅ Custom component library with shadcn-vue extensions
• ✅ Auto-generated routing system (based on file structure)
• ✅ English and Simplified Chinese locale resources with vue-i18n (some page copy remains hardcoded)
• ✅ Form validation with tanstack/vue-form + Zod
• ✅ Reusable data tables with TanStack Table, query/mutation examples with TanStack Query, and charts with Unovis
• ✅ Animation support (AutoAnimate, Motion-V, TW Animate CSS)

🛠️ Tech Stack & Version Constraints

Category	Tools & Libraries (Major Versions)
Core Framework	Vue 3.5+, TypeScript 6+
UI Components	shadcn-vue, reka-ui 2+, @lucide/vue
Build Tool	Vite 8+, @vitejs/plugin-vue 6+
State Management	Pinia 4+, pinia-plugin-persistedstate 4+
Routing	vue-router 5+, vite-plugin-vue-layouts 0.11+
Styling	Tailwind CSS 4+, tw-animate-css 1+
Data Handling	TanStack Vue Query 5+, TanStack Vue Table 9+
Form Validation	TanStack Vue Form, Zod 4+
Animation	@formkit/auto-animate 0.10+, motion-v 2+
Internationalization	vue-i18n 11+
HTTP Client	ofetch
Linting & Formatting	ESLint 10+, @antfu/eslint-config 9+
Auto Import	unplugin-auto-import 21+, unplugin-vue-components 32+

🚀 Quick Start

Prerequisites

• Node.js ≥ 22.15, as declared in package.json; CI uses Node.js 22.
• Use the pnpm version specified by packageManager in package.json (currently 11.28.4).
• TypeScript is installed as a project dependency; no global installation is needed.

Installation

1. Clone the repository

   git clone https://github.com/Whbbit1999/shadcn-vue-admin.git

2. Navigate to project directory

   cd shadcn-vue-admin

3. Install dependencies

   pnpm install

4. Start development server

   pnpm dev

Available Scripts

pnpm dev             # Start development server
pnpm build           # Build for production (vue-tsc + vite build)
pnpm build:analyze   # Build with bundle visualizer (ANALYZE=true)
pnpm preview         # Preview production build
pnpm lint            # ESLint check
pnpm lint:fix        # Auto fix lint issues
pnpm test            # Run unit tests in watch mode
pnpm test:run        # Run unit tests once
pnpm test:coverage   # Run unit tests with coverage
pnpm release         # Bump version with bumpp

📖 Advanced Guides

Dependency Maintenance

• Dependency ranges are declared in package.json; pnpm-lock.yaml records the resolved versions. CI installs with pnpm install --frozen-lockfile.
• Git hooks use simple-git-hooks: pre-commit runs nano-staged to fix lint issues in staged files, and pre-push runs pnpm build.
• Pull request CI runs lint, build and test coverage checks for changes beyond Markdown files.

Theme Customization

Use tweakcn as a starting point for custom themes. Update the base CSS variables in src/assets/index.css under :root and .dark, and adjust the @theme inline mappings when needed. The selectable color themes have their own overrides in src/assets/themes.css; update those too when customizing a selectable theme.

Layout Customization

For pages in pages/errors/ and pages/auth/ that you don’t want to use the default layout:

Create a same-name file in pages/: src/pages/errors.vue src/pages/auth.vue

<template>
  <router-view />
</template>

<route lang="yml">
meta:
  layout: false
</route>

The project already uses this pattern in src/pages/auth.vue and src/pages/errors.vue. For a new directory, add an index.vue if its base path should redirect to a child page:

<script lang="ts" setup>
const router = useRouter()
router.replace('/errors/404')
</script>

API Configuration

When connecting a backend, use .env.example as a reference for your local environment configuration:

• VITE_SERVER_API_URL: backend origin.
• VITE_SERVER_API_PREFIX: API path prefix (defaults to /api).
• VITE_SERVER_API_TIMEOUT: request timeout in milliseconds (defaults to 5000).

src/lib/api-client.ts provides the shared ofetch client, and src/services/api/ contains API examples. The Tasks page currently uses src/pages/tasks/data/tasks.json; the task API examples are not wired into that page.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Credits

• Developer: Whbbit1999
• Original Design: shadcn-admin