Quick Start

Source Files

This page is generated from the following source files:

• package.json
• .env.example
• vite.config.ts
• README.md
• knip.config.ts
• src/assets/brand-icons/index.ts
• src/components/data-table/index.ts
• eslint.config.js
• src/main.tsx
• src/vite-env.d.ts

Shadcn Admin is an admin dashboard UI built with React, ShadcnUI, and Vite. The project focuses on responsiveness and accessibility, providing a reusable collection of dashboard UI components for modern web applications. It includes features such as light/dark mode, responsive layouts, built-in sidebar components, global search command, and over 10 pre-built pages with RTL (Right-to-Left) support (README.md:1-23).

The tech stack comprises ShadcnUI (TailwindCSS + RadixUI) for UI components, Vite as the build tool, TanStack Router for routing, TypeScript for type checking, ESLint and Prettier for linting and formatting, Lucide Icons and Tabler Icons for iconography, and Clerk for authentication (README.md:61-76).

Prerequisites Environment Setup

System Requirements

The project requires Node.js and a package manager. Based on the project configuration, pnpm is the recommended package manager for installation and running scripts.

Core Dependencies

The project depends on React 19.2.4 and React DOM 19.2.4 as the foundational libraries. The UI layer is built on Radix UI primitives including alert-dialog, avatar, checkbox, dialog, dropdown-menu, select, and other accessible components. State management is handled by Zustand 5.0.12, while form management uses react-hook-form 7.72.0 with Zod 4.3.6 for schema validation (package.json:1-59).

Data fetching and caching are powered by TanStack Query 5.95.2, and routing is managed by TanStack Router 1.168.4. The styling solution combines TailwindCSS 4.2.2 with class-variance-authority and tailwind-merge for utility-first CSS with variant management.

Development Dependencies

The development environment includes TypeScript ~6.0.2 for type checking, Vite 8.0.3 as the build tool with the React SWC plugin for fast refresh, ESLint 10.1.0 with TypeScript ESLint and React-specific plugins for code quality, and Prettier 3.8.1 with import sorting and TailwindCSS plugins for code formatting (package.json:60-83).

Environment Variables

The project requires a Clerk publishable key for authentication functionality. This must be configured in the environment before running the application:

bash
1VITE_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key

The environment variable is defined in the .env.example file and must be set for the authentication features to work properly (.env.example:1-1).

Build Configuration

Vite Setup

The build system is configured through Vite with three primary plugins. The TanStack Router plugin enables file-based routing with automatic code splitting for optimized bundle sizes. The React plugin uses SWC for fast compilation and hot module replacement. The TailwindCSS plugin integrates the utility-first CSS framework directly into the build pipeline (vite.config.ts:1-22).

typescript
1// vite.config.ts
2export default defineConfig({
3  plugins: [
4    tanstackRouter({
5      target: 'react',
6      autoCodeSplitting: true,
7    }),
8    react(),
9    tailwindcss(),
10  ],
11  resolve: {
12    alias: {
13      '@': path.resolve(__dirname, './src'),
14    },
15  },
16})

The configuration also sets up a path alias @ pointing to the ./src directory, enabling clean imports throughout the codebase (vite.config.ts:17-21).

TypeScript Integration

TypeScript support for Vite-specific types is provided through the vite-env.d.ts declaration file, which references the Vite client types. This ensures proper type checking for Vite-specific features like import.meta.env (src/vite-env.d.ts:1-1).

Running the Project

Installation Steps

The recommended approach to get started with the project is as follows:

1. Clone the repository:

   bash
   1git clone https://github.com/satnaing/shadcn-admin.git

2. Navigate to the project directory:

   bash
   1cd shadcn-admin

3. Install dependencies:

   bash
   1pnpm install

4. Start the development server:

   bash
   1pnpm run dev

These steps are documented in the project README and represent the standard workflow for local development (README.md:77-101).

Available Scripts

The project provides several npm scripts for different development tasks:

(package.json:6-14)

Recommended Quick Start Path

For the fastest path to a running application:

bash
1git clone https://github.com/satnaing/shadcn-admin.git
2cd shadcn-admin
3pnpm install
4pnpm run dev

This sequence clones the repository, installs all dependencies including React, TanStack libraries, Radix UI components, and development tools, then starts the Vite development server.

Application Entry Point

Bootstrap Process

The application entry point is located in src/main.tsx. It initializes the React application with StrictMode enabled for highlighting potential problems during development. The bootstrap process sets up a comprehensive provider hierarchy to wrap the application (src/main.tsx:1-20).

QueryClient Configuration

The TanStack QueryClient is configured with custom retry logic and error handling. In development mode, query retries are disabled (failureCount >= 0 returns false), while in production, queries retry up to 3 times before failing. Queries also skip retrying for 401 and 403 HTTP errors (src/main.tsx:21-73).

typescript
1const queryClient = new QueryClient({
2  defaultOptions: {
3    queries: {
4      retry: (failureCount, error) => {
5        if (import.meta.env.DEV) console.log({ failureCount, error })
6        if (failureCount >= 0 && import.meta.env.DEV) return false
7        if (failureCount > 3 && import.meta.env.PROD) return false
8        return !(
9          error instanceof AxiosError &&
10          [401, 403].includes(error.response?.status ?? 0)
11        )
12      },
13      refetchOnWindowFocus: import.meta.env.PROD,
14      staleTime: 10 * 1000, // 10s
15    },
16  },
17})

The QueryCache includes error handlers that respond to specific HTTP status codes: 401 errors trigger a session expired notification and redirect to sign-in, 500 errors navigate to an error page in production only (to avoid disrupting HMR in development), and 403 errors are handled for forbidden access scenarios (src/main.tsx:51-72).

Provider Hierarchy

The application is wrapped in a nested provider structure that establishes the application context:

正在加载图表渲染器...

The hierarchy flows from the outermost StrictMode wrapper through QueryClientProvider for data fetching, ThemeProvider for light/dark mode, FontProvider for typography, DirectionProvider for RTL/LTR support, and finally RouterProvider for navigation (src/main.tsx:90-107).

Router Initialization

The router is created using TanStack Router's createRouter function with the generated route tree. It is configured with intent-based preloading and a stale time of 0 for immediate data fetching. The router instance is registered with TypeScript for type safety across the application (src/main.tsx:75-88).

Verification Health Checks

Development Server Verification

After running pnpm run dev, the Vite development server starts and provides output indicating the server is running. The default port configuration needs confirmation from the Vite output or configuration files (需要确认: exact port number and localhost URL from Vite startup output).

Build Verification

To verify the production build works correctly:

bash
1pnpm run build
2pnpm run preview

The build script first runs TypeScript type checking with tsc -b, then executes vite build to create the production bundle. The preview script serves the built files for local testing (package.json:8-10).

Code Quality Verification

Run the linting and formatting checks to ensure code quality:

bash
1pnpm run lint
2pnpm run format:check

These commands verify the codebase adheres to ESLint rules and Prettier formatting standards. The ESLint configuration enforces rules including no console statements (treated as errors), TypeScript strict unused variable checks with underscore-prefixed exceptions, and consistent type imports (eslint.config.js:32-56).

Troubleshooting

Common Issue 1: Missing Environment Variables

Problem: Authentication features fail or the application throws errors related to Clerk configuration.

Solution: Ensure the .env file exists in the project root with a valid Clerk publishable key:

bash
1VITE_CLERK_PUBLISHABLE_KEY=pk_test_your_key_here

Copy the .env.example file to .env and populate the value with a valid key from the Clerk dashboard.

Common Issue 2: Type Errors During Build

Problem: The pnpm run build command fails with TypeScript errors.

Solution: The build script runs tsc -b before Vite build, which performs full type checking. Address any type errors by ensuring all imports are correct and types are properly defined. The project uses TypeScript ~6.0.2 with strict checking enabled (package.json:8).

Common Issue 3: Unused Dependencies or Exports

Problem: The pnpm run knip script reports unused files, dependencies, or exports.

Solution: Knip is configured to analyze the project for dead code. Note that certain paths are ignored in the configuration, including src/components/ui/**, src/components/layout/app-title.tsx, and src/tanstack-table.d.ts (knip.config.ts:3-9). Review the Knip output and either remove unused code or add necessary paths to the ignore list.

Common Issue 4: ESLint Errors on Console Statements

Problem: ESLint reports errors on console.log statements.

Solution: The ESLint configuration treats no-console as an error. For development debugging, the main.tsx file uses // eslint-disable-next-line no-console comments to allow specific console statements in development mode (src/main.tsx:25-26, eslint.config.js:32).

Common Issue 5: Hot Module Replacement Not Working

Problem: Changes to files do not reflect in the browser without manual refresh.

Solution: Ensure the Vite development server is running with pnpm run dev. The React plugin uses SWC for fast refresh. If HMR still fails, check that files are not being ignored by the ESLint configuration (the dist and src/components/ui directories are ignored for linting but should not affect HMR) (eslint.config.js:10).

Next Steps

After successfully running the project, explore the following areas to understand the codebase in depth:

1. Component Library: Review the customized ShadcnUI components in src/components/ui/ to understand the RTL modifications and customizations made for this project.

2. Routing Structure: Examine the TanStack Router configuration and generated route tree to understand the application's navigation structure.

3. State Management: Study the Zustand stores, particularly the auth store referenced in the main.tsx error handling, to understand global state patterns.

4. Data Table Components: Explore the data-table module which exports pagination, column headers, toolbar, and bulk action components for building complex tables (src/components/data-table/index.ts:1-4).

5. Brand Icons: Utilize the pre-configured brand icons for social and platform integrations, including Discord, Docker, Facebook, Figma, GitHub, GitLab, Gmail, Medium, Notion, Skype, Slack, Stripe, Telegram, Trello, WhatsApp, and Zoom (src/assets/brand-icons/index.ts:1-16).

For detailed usage instructions, configuration options, and advanced features, refer to the Usage Guide and Configuration sections of the documentation.