CoreUI Free React Admin Template - Architecture

This document provides a comprehensive overview of the CoreUI Free React Admin Template architecture, design patterns, and technical implementation details.

Project Overview
Technology Stack
Architectural Pattern
Directory Structure
Core Components
Routing System
State Management
Styling Architecture
Build System
Performance Optimizations
Browser Support

Project Overview

The CoreUI Free React Admin Template is a professional admin dashboard built on React 19, CoreUI React components, and Bootstrap 5. It follows modern React patterns with functional components, Hooks, and a component-based architecture.

Key Features:

Single Page Application (SPA) with client-side routing
Responsive design with Bootstrap 5 grid system
Dark/Light theme support with automatic detection
Lazy loading and code splitting for optimal performance
Redux-based state management
Modular and extensible component architecture

Technology Stack

Frontend Core

Technology	Version	Purpose
React	19.2.4	UI library for building component-based interfaces
React DOM	19.2.4	DOM rendering and manipulation
React Router DOM	7.13.2	Client-side routing and navigation
Redux	5.0.1	Predictable state container
React-Redux	9.2.0	React bindings for Redux

UI Framework

Library	Version	Purpose
@coreui/coreui	5.6.1	CoreUI CSS framework based on Bootstrap 5
@coreui/react	5.10.0	CoreUI React components
@coreui/icons	3.0.1	CoreUI icon set
@coreui/icons-react	2.3.0	CoreUI icons as React components
@coreui/utils	2.0.2	Utility functions for CoreUI
simplebar-react	3.3.2	Custom scrollbar component

Data Visualization

Library	Version	Purpose
Chart.js	4.5.1	HTML5 charting library
@coreui/chartjs	4.2.0	CoreUI Chart.js themes and defaults
@coreui/react-chartjs	3.0.0	React wrapper for Chart.js with CoreUI styling

Build Tools & Development

Tool	Version	Purpose
Vite	8.0.3	Fast build tool and dev server with HMR
@vitejs/plugin-react	6.0.1	Vite plugin for React Fast Refresh
Sass	1.98.0	CSS preprocessor for styling
PostCSS	8.5.8	CSS transformation with autoprefixer
Autoprefixer	10.4.27	Automatic vendor prefixing
ESLint	9.39.2	JavaScript linting and code quality
Prettier	3.8.1	Code formatting

Utilities

Library	Version	Purpose
classnames	2.5.1	Conditional CSS class management
prop-types	15.8.1	Runtime type checking for React props
core-js	3.49.0	Polyfills for JavaScript features
@popperjs/core	2.11.8	Tooltip and popover positioning

Architectural Pattern

Component-Based Architecture

The application follows a functional component architecture with React Hooks:

┌──────────────────────────────────────────┐
│           Application (App.jsx)          │
│  - HashRouter                            │
│  - Theme Management                      │
│  - Route Configuration                   │
└──────────────────────────────────────────┘
                    ↓
    ┌───────────────┴────────────────┐
    │                                │
┌───▼────┐                  ┌────────▼───────┐
│ Public │                  │   Protected    │
│ Routes │                  │     Routes     │
│        │                  │ (DefaultLayout)│
│ Login  │                  └───────┬────────┘
│Register│                          │
│ 404    │              ┌───────────┼────────────┐
│ 500    │              │           │            │
└────────┘         ┌────▼────┐ ┌────▼─────┐ ┌────▼─────┐
                   │AppHeader│ │AppSidebar│ │AppContent│
                   └─────────┘ └──────────┘ └────┬─────┘
                                                 │
                                         ┌───────▼─────────┐
                                         │ View Components │
                                         │ (Dashboard,     │
                                         │  Forms, etc.)   │
                                         └─────────────────┘

Single Page Application (SPA) Pattern

The template uses client-side routing with HashRouter:

Initial Load: HTML shell loads, React initializes
Route Matching: React Router matches URL to component
Lazy Loading: Component bundles load on-demand
Rendering: Component renders with layout wrapper
Navigation: Client-side transitions without page reload

State Management Pattern

Redux manages global application state:

Store (store.js)
  ├── theme (light/dark/auto)
  ├── sidebarShow (boolean)
  └── sidebarUnfoldable (boolean)

Component-level state uses React Hooks (useState, useReducer).

Directory Structure

coreui-free-react-admin-template/
│
├── public/                      # Static assets (served as-is)
│   ├── favicon.ico
│   └── robots.txt
│
├── src/                         # Source code
│   │
│   ├── assets/                  # Application assets
│   │   ├── brand/              # Logo components (logo.jsx, sygnet.jsx)
│   │   └── images/             # Image files (avatars, etc.)
│   │
│   ├── components/              # Reusable UI components
│   │   ├── AppBreadcrumb.jsx   # Breadcrumb navigation
│   │   ├── AppContent.jsx      # Main content area wrapper
│   │   ├── AppFooter.jsx       # Footer component
│   │   ├── AppHeader.jsx       # Header component
│   │   ├── AppSidebar.jsx      # Sidebar navigation
│   │   ├── AppSidebarNav.jsx   # Sidebar navigation renderer
│   │   ├── DocsComponents.jsx  # Documentation component showcase
│   │   ├── DocsExample.jsx     # Code example wrapper
│   │   ├── DocsIcons.jsx       # Icon showcase
│   │   ├── DocsLink.jsx        # Documentation link
│   │   ├── header/             # Header sub-components
│   │   │   └── AppHeaderDropdown.jsx  # User dropdown menu
│   │   └── index.js            # Component barrel export
│   │
│   ├── layout/                  # Layout wrapper components
│   │   └── DefaultLayout.jsx   # Main application layout
│   │
│   ├── views/                   # Page/view components
│   │   ├── dashboard/          # Dashboard page
│   │   │   └── Dashboard.jsx
│   │   ├── base/               # Base UI component examples
│   │   │   ├── accordion/
│   │   │   ├── breadcrumbs/
│   │   │   ├── cards/
│   │   │   ├── carousels/
│   │   │   ├── collapses/
│   │   │   ├── list-groups/
│   │   │   ├── navs/
│   │   │   ├── paginations/
│   │   │   ├── placeholders/
│   │   │   ├── popovers/
│   │   │   ├── progress/
│   │   │   ├── spinners/
│   │   │   ├── tables/
│   │   │   ├── tabs/
│   │   │   └── tooltips/
│   │   ├── buttons/            # Button examples
│   │   ├── charts/             # Chart examples
│   │   ├── forms/              # Form examples
│   │   ├── icons/              # Icon examples
│   │   ├── notifications/      # Notification examples
│   │   ├── widgets/            # Widget examples
│   │   └── pages/              # Special pages
│   │       ├── login/          # Login page
│   │       ├── register/       # Registration page
│   │       ├── page404/        # 404 error page
│   │       └── page500/        # 500 error page
│   │
│   ├── scss/                    # Global stylesheets
│   │   ├── style.scss          # Main stylesheet (imports CoreUI)
│   │   ├── _custom.scss        # Custom style overrides
│   │   ├── examples.scss       # Documentation example styles
│   │   └── vendors/            # Third-party style overrides
│   │
│   ├── App.jsx                  # Root application component
│   ├── index.jsx                # Application entry point
│   ├── routes.js                # Route definitions
│   ├── _nav.jsx                 # Sidebar navigation configuration
│   └── store.js                 # Redux store configuration
│
├── build/                       # Build utilities (optional)
├── node_modules/                # Dependencies
├── index.html                   # HTML entry point
├── vite.config.mjs              # Vite build configuration
├── eslint.config.mjs            # ESLint configuration
├── package.json                 # Project metadata and dependencies
├── .prettierrc.js               # Prettier configuration
├── .browserslistrc              # Browser compatibility targets
├── .editorconfig                # Editor configuration
└── README.md                    # Project documentation

Core Components

Application Component (App.jsx)

The root component that:

Sets up HashRouter for client-side routing
Manages theme initialization and persistence
Provides Suspense boundaries for lazy-loaded routes
Defines top-level route structure

Key Features:

Theme detection from URL parameters
Redux integration for theme state
Fallback spinner during component loading

Layout System

DefaultLayout (layout/DefaultLayout.jsx)

The main application layout wrapper that composes:

AppSidebar: Collapsible navigation sidebar
AppHeader: Top navigation bar with breadcrumbs and user menu
AppContent: Main content area with routing
AppFooter: Footer with version and links

Responsibility: Provides consistent layout structure for authenticated views.

Navigation Components

AppSidebar (components/AppSidebar.jsx):

Renders collapsible sidebar
Integrates with Redux for show/hide state
Uses AppSidebarNav for menu rendering
Includes branding section

AppSidebarNav (components/AppSidebarNav.jsx):

Recursive navigation renderer
Supports nested menu items
Renders CoreUI nav components (CNavItem, CNavGroup, CNavTitle)
Handles active state based on current route

AppHeader (components/AppHeader.jsx):

Fixed top navigation bar
Sidebar toggle button
Breadcrumb navigation
User dropdown menu
Theme switcher

View Components

View components are page-level components that:

Render specific application features (Dashboard, Forms, Charts)
Use CoreUI React components for UI
Connect to Redux when needed for global state
Implement business logic and data fetching

Example Structure:

const Dashboard = () => {
  const [data, setData] = useState([])

  useEffect(() => {
    // Fetch dashboard data
  }, [])

  return (
    <>
      <WidgetsDropdown />
      <CCard>
        <CCardBody>
          {/* Dashboard content */}
        </CCardBody>
      </CCard>
    </>
  )
}

Routing System

React Router DOM v7

The application uses React Router DOM for declarative routing:

Configuration (App.jsx):

<HashRouter>
  <Routes>
    <Route path="/login" element={<Login />} />
    <Route path="/register" element={<Register />} />
    <Route path="/404" element={<Page404 />} />
    <Route path="/500" element={<Page500 />} />
    <Route path="*" element={<DefaultLayout />} />
  </Routes>
</HashRouter>

Protected Routes (DefaultLayout.jsx + routes.js):

// routes.js - Route definitions
const routes = [
  { path: '/', exact: true, name: 'Home' },
  { path: '/dashboard', name: 'Dashboard', element: Dashboard },
  { path: '/base', name: 'Base', element: Cards, exact: true },
  // ... more routes
]

// DefaultLayout.jsx - Route rendering
<Suspense fallback={<CSpinner />}>
  <Routes>
    {routes.map((route, idx) => (
      <Route
        key={idx}
        path={route.path}
        exact={route.exact}
        name={route.name}
        element={<route.element />}
      />
    ))}
  </Routes>
</Suspense>

Lazy Loading & Code Splitting

All routes use React.lazy() for dynamic imports:

const Dashboard = React.lazy(() => import('./views/dashboard/Dashboard'))
const Login = React.lazy(() => import('./views/pages/login/Login'))

Benefits:

Smaller initial bundle size
Faster first page load
Components load only when navigated to
Automatic code splitting by Vite

Navigation Configuration

Navigation structure defined in _nav.jsx:

export default [
  {
    component: CNavItem,
    name: 'Dashboard',
    to: '/dashboard',
    icon: <CIcon icon={cilSpeedometer} />,
    badge: {
      color: 'info',
      text: 'NEW',
    },
  },
  {
    component: CNavGroup,
    name: 'Base',
    icon: <CIcon icon={cilPuzzle} />,
    items: [
      {
        component: CNavItem,
        name: 'Accordion',
        to: '/base/accordion',
      },
      // ... nested items
    ],
  },
]

State Management

Redux Store Architecture

Store Configuration (store.js):

import { legacy_createStore as createStore } from 'redux'

const initialState = {
  sidebarShow: true,
  sidebarUnfoldable: false,
  theme: 'light',
}

const changeState = (state = initialState, { type, ...rest }) => {
  switch (type) {
    case 'set':
      return { ...state, ...rest }
    default:
      return state
  }
}

const store = createStore(changeState)
export default store

State Usage in Components

Reading State (useSelector):

import { useSelector } from 'react-redux'

const MyComponent = () => {
  const sidebarShow = useSelector((state) => state.sidebarShow)
  const theme = useSelector((state) => state.theme)

  return <div>Sidebar: {sidebarShow ? 'Visible' : 'Hidden'}</div>
}

Updating State (useDispatch):

import { useDispatch } from 'react-redux'

const MyComponent = () => {
  const dispatch = useDispatch()

  const toggleSidebar = () => {
    dispatch({ type: 'set', sidebarShow: false })
  }

  return <button onClick={toggleSidebar}>Hide Sidebar</button>
}

Theme Management

CoreUI provides useColorModes hook for theme control:

import { useColorModes } from '@coreui/react'

const App = () => {
  const { colorMode, setColorMode } = useColorModes('coreui-theme-key')

  // Set theme: 'light', 'dark', or 'auto'
  setColorMode('dark')

  return <div>Current theme: {colorMode}</div>
}

Theme persists in localStorage and syncs with Redux state.

Styling Architecture

Sass/SCSS Structure

Main Stylesheet (src/scss/style.scss):

@use "@coreui/coreui/scss/coreui" as * with (
  $enable-deprecation-messages: false
);

// Custom variables and overrides
@import 'custom';

Custom Overrides (src/scss/_custom.scss):

// Override CoreUI/Bootstrap variables
$primary: #321fdb;
$secondary: #ced2d8;

// Custom styles
.my-custom-class {
  // styles
}

CSS Custom Properties (CSS Variables)

CoreUI uses CSS custom properties for theming:

:root {
  --cui-primary: #321fdb;
  --cui-secondary: #ced2d8;
  --cui-body-bg: #ebedef;
  --cui-body-color: #4f5d73;
}

[data-coreui-theme="dark"] {
  --cui-body-bg: #2b3035;
  --cui-body-color: #b4bac0;
}

Usage in Components:

<div style={{ backgroundColor: 'var(--cui-primary)' }}>Content</div>

Component Styling

Inline Styles:

<CCard style={{ marginBottom: '1rem' }}>

Class Names (with classnames utility):

import classNames from 'classnames'

const buttonClass = classNames({
  'btn': true,
  'btn-primary': isPrimary,
  'btn-disabled': isDisabled,
})

<button className={buttonClass}>Click</button>

Bootstrap Utilities:

<CCard className="mb-4 shadow-sm">
  <CCardBody className="p-4 d-flex justify-content-between">

Build System

Vite Configuration

File: vite.config.mjs

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'node:path'
import autoprefixer from 'autoprefixer'

export default defineConfig({
  base: './',
  build: {
    outDir: 'build',
  },
  css: {
    postcss: {
      plugins: [autoprefixer()],
    },
  },
  plugins: [react()],
  resolve: {
    alias: {
      'src/': `${path.resolve(__dirname, 'src')}/`,
    },
  },
  server: {
    port: 3000,
  },
})

Build Process

Development Build:

Vite starts dev server on port 3000
ESBuild compiles JSX to JavaScript
PostCSS processes Sass/SCSS with autoprefixer
Hot Module Replacement (HMR) for instant updates

Production Build:

vite build command
Code minification and tree-shaking
Asset optimization (images, fonts)
CSS extraction and minification
Source maps generation
Output to build/ directory

Build Output:

build/
├── assets/
│   ├── index-[hash].js      # Main bundle
│   ├── [component]-[hash].js # Lazy-loaded chunks
│   └── index-[hash].css     # Extracted CSS
├── index.html               # HTML entry
└── favicon.ico              # Static assets

Code Splitting Strategy

Automatic Splitting:

Each lazy-loaded route becomes a separate chunk
Vendor libraries (React, CoreUI) in separate vendor chunk
Dynamic imports create split points

Manual Splitting (if needed):

const HeavyComponent = React.lazy(() =>
  import(/* webpackChunkName: "heavy" */ './HeavyComponent')
)

Performance Optimizations

Implemented Optimizations

Lazy Loading: All routes lazy-loaded with React.lazy()
Code Splitting: Separate bundles per route
Tree Shaking: Unused code eliminated by Vite
Asset Optimization: Images and fonts optimized
CSS Extraction: Separate CSS bundle for caching
Hash-based Caching: File names include content hash

Component Optimization

React.memo for expensive renders:

const ExpensiveComponent = React.memo(({ data }) => {
  return <div>{/* Heavy rendering */}</div>
})

useMemo for computed values:

const sortedData = useMemo(() => {
  return data.sort((a, b) => a.value - b.value)
}, [data])

useCallback for stable function references:

const handleClick = useCallback(() => {
  console.log('Clicked')
}, [])

Bundle Size Management

Strategies:

Use named imports: import { CButton } from '@coreui/react'
Avoid importing entire libraries
Check bundle size with npm run build
Use Vite's rollup visualizer for analysis

Browser Support

Target Browsers

Defined in .browserslistrc:

> 0.5%
last 2 versions
Firefox ESR
not dead
not IE 11

Polyfills

core-js provides polyfills for:

ES6+ features
Promise, Array methods
Object methods
Modern JavaScript APIs

Progressive Enhancement

Modern features with fallbacks
CSS Grid with flexbox fallback
Modern color modes with theme classes

Security Considerations

Best Practices

Content Security Policy: Configure CSP headers
XSS Prevention: React escapes content by default
Dependency Auditing: Run npm audit regularly
Environment Variables: Use .env files (not committed)
HTTPS: Serve over HTTPS in production

React Security

Avoid dangerouslySetInnerHTML unless necessary
Validate user input before rendering
Use PropTypes for type safety
Keep dependencies updated

Deployment

Static Hosting

The application builds to static files suitable for:

Netlify
Vercel
GitHub Pages
AWS S3 + CloudFront
Any static file server

Build for Production

npm run build

Output in build/ directory ready for deployment.

HashRouter for Static Hosts

Uses HashRouter for GitHub Pages compatibility:

URLs: https://example.com/#/dashboard
No server-side routing configuration needed
Works with any static host

This architecture provides a solid foundation for building modern, performant admin dashboards with React and CoreUI. The modular structure allows for easy extension and customization while maintaining code quality and best practices.

Uh oh!

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History