Project Structure

Understanding the React template’s architecture is crucial for efficient development and customization.

Overview

The React admin template follows a modular, feature-based architecture designed for scalability and maintainability.

Component-Driven

Reusable components organized by functionality and complexity levels

Type-Safe

Full TypeScript integration with comprehensive type definitions

Scalable

Feature-based structure supports large-scale application development

Directory Structure

Directorysrc/
- Directoryassets/ - Static assets and global styles
  - Directorystyles/
    index.css - Global CSS and Tailwind imports
  - react.svg - React logo asset
- Directorycomponents/ - Reusable UI components
  - DirectoryCharts/ - ApexCharts wrapper components
    …
  - DirectoryHiExport/ - Data export functionality
    …
  - DirectoryHiForm/ - Dynamic form builder
    …
  - DirectoryHiTable/ - Advanced data table
    …
  - DirectoryRichTextEditor/ - WYSIWYG text editor
    …
  - Directoryui/ - shadcn/ui component library
    …
- Directoryconstant/ - Application constants
  - index.ts - General application constants
  - themeColors.ts - Theme color definitions
- Directoryhooks/ - Custom React hooks
  - useLocalStorage.ts - localStorage integration
  - useMediaQuery.ts - Responsive breakpoints
  - useThemeColor.ts - Theme management
- Directorylayouts/ - Layout components and structures
  - Directorycomponents/ - Layout-specific components
    …
  - DirectorysideLayout/ - Sidebar navigation layout
    …
  - DirectorytopLayout/ - Top navigation layout
    …
- Directorylib/ - Utility functions and configurations
  - i18n.ts - Internationalization setup
  - utils.ts - Common utility functions
- Directorylocales/ - Translation files
  - en.json - English translations
  - zh.json - Chinese translations
- Directorypages/ - Application pages and features
  - Directoryanalyze/ - Analytics dashboard
    …
  - Directoryauth/ - Authentication pages
    …
  - Directorydashboard/ - Main dashboard
    …
  - Directorymanagement/ - Business management modules
    …
  - Directorysettings/ - User settings
    …
  - DirectoryUIElement/ - Component showcase
    …
- Directoryrouter/ - Routing configuration
  - index.tsx - Route definitions
  - types.ts - Router type definitions
- Directorystore/ - Zustand state management
  - themeStore.ts - Theme state
  - uiStore.ts - UI state management
- Directorytypes/ - Global TypeScript definitions
  - …
Directorypublic/ - Static public assets
- …
Directorydist/ - Production build output
- …
Configuration files (package.json, vite.config.ts, etc.)

Core Directories

Components Architecture

The components directory is organized by functionality and complexity:

src/components/
├── Charts/              # ApexCharts integration
│   ├── AreaChart.tsx   # Area chart component
│   ├── BarChart.tsx    # Bar chart component
│   ├── BaseChart.tsx   # Base chart wrapper
│   └── index.ts        # Chart exports
├── HiTable/            # Advanced data table
│   ├── HiTable.tsx     # Main table component
│   ├── components/     # Table sub-components
│   ├── hooks/          # Table-specific hooks
│   └── types.ts        # Table type definitions
├── ui/                 # shadcn/ui primitives
│   ├── button.tsx      # Button component
│   ├── dialog.tsx      # Modal dialog
│   └── ...             # 48 UI components
└── ...

Pages Organization

Pages are organized by business domain:

src/pages/
├── auth/               # Authentication
│   ├── login.tsx       # Login page
│   ├── register.tsx    # Registration page
│   └── components/     # Auth-specific components
├── dashboard/          # Main dashboard
│   ├── index.tsx       # Dashboard overview
│   └── components/     # Dashboard components
├── management/         # Business modules
│   ├── user/           # User management
│   ├── product/        # Product management
│   ├── order/          # Order management
│   ├── invoice/        # Invoice system
│   ├── calendar/       # Calendar events
│   ├── chat/           # Chat system
│   ├── mail/           # Email management
│   └── fileManager/    # File management
└── settings/           # Application settings

Key Configuration Files

Package.json

Central dependency and script management:

{
"name": "react_admin_template",
"type": "module",
"engines": {
  "node": ">=20.19.0"
},
"scripts": {
  "dev": "vite --host 0.0.0.0",
  "build": "tsc -b && vite build",
  "check": "tsc --noEmit -p tsconfig.app.json",
  "lint": "eslint ."
},
"dependencies": {
  "react": "^19.1.1",
  "typescript": "~5.8.3",
  "@tailwindcss/vite": "^4.1.12"
}
}

Vite Configuration

Modern build tool setup:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import * as path from 'path'

export default defineConfig({
plugins: [react(), tailwindcss()],
resolve: {
  alias: {
    '@': path.resolve(__dirname, './src')
  }
},
server: {
  port: 9000
}
})

TypeScript Configuration

Strict type checking setup:

{
"compilerOptions": {
  "target": "ES2022",
  "useDefineForClassFields": true,
  "lib": ["ES2022", "DOM", "DOM.Iterable"],
  "module": "ESNext",
  "skipLibCheck": true,
  "moduleResolution": "bundler",
  "allowImportingTsExtensions": true,
  "verbatimModuleSyntax": true,
  "moduleDetection": "force",
  "noEmit": true,
  "jsx": "react-jsx",
  "strict": true,
  "noUnusedLocals": true,
  "noUnusedParameters": true,
  "erasableSyntaxOnly": true,
  "noFallthroughCasesInSwitch": true,
  "noUncheckedSideEffectImports": true,
  "baseUrl": ".",
  "paths": {
    "@/*": ["./src/*"]
  }
}
}

Import Path Conventions

The template uses consistent import patterns for better organization:

// Absolute imports using @ alias
import { Button } from '@/components/ui/button'
import { useThemeStore } from '@/store/themeStore'
import { User } from '@/types'

// Relative imports for local files
import './styles.css'
import { validateForm } from '../utils/validation'

// Library imports
import React, { useState, useEffect } from 'react'
import { useNavigate } from 'react-router-dom'
import { z } from 'zod'

State Management Structure

Zustand stores are organized by domain:

src/store/
├── index.ts            # Store exports and types
├── themeStore.ts       # Theme management
├── themeColorStore.ts  # Color customization
└── uiStore.ts          # UI state (sidebar, modals)

// Example store usage:
import { useThemeStore } from '@/store/themeStore'

const { theme, setTheme } = useThemeStore()

Routing Structure

React Router v7 with lazy loading:

// src/router/index.tsx
import { createBrowserRouter } from 'react-router-dom'
import { lazy } from 'react'

// Lazy-loaded pages for code splitting
const Dashboard = lazy(() => import('@/pages/dashboard'))
const UserManagement = lazy(() => import('@/pages/management/user'))

export const router = createBrowserRouter([
  {
    path: '/',
    element: <AppLayout />,
    children: [
      { index: true, element: <Dashboard /> },
      { path: 'management/users', element: <UserManagement /> }
    ]
  }
])

Development Conventions

File Naming

Components: PascalCase (UserForm.tsx)
Pages: PascalCase (UserManagement.tsx)
Hooks: camelCase starting with ‘use’ (useUserData.ts)
Utils: camelCase (formatDate.ts)
Types: PascalCase (User.ts or in types/index.ts)

Component Structure

// Standard component structure
import React from 'react'
import { cn } from '@/lib/utils'

// Props interface
interface ComponentProps {
  className?: string
  children?: React.ReactNode
  // ... other props
}

// Main component
export const Component: React.FC<ComponentProps> = ({
  className,
  children
}) => {
  return (
    <div className={cn('base-classes', className)}>
      {children}
    </div>
  )
}

Build Output Structure

Production build creates optimized assets:

dist/
├── assets/
│   ├── index-[hash].js     # Main application bundle
│   ├── vendor-[hash].js    # Third-party dependencies
│   └── index-[hash].css    # Compiled styles
├── index.html              # Entry HTML file
└── favicon.ico            # App favicon

Next Steps

Now that you understand the project structure:

Core Components

Explore HiTable, HiForm, and other powerful business components

Feature Modules

Learn about user management, dashboard, and other business modules

Customization

Discover theming, styling, and customization options

Understanding this structure will help you navigate and extend the React template efficiently! 🏗️