gentelella/CLAUDE.md

Gentelella Admin is a free to use Bootstrap admin template

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

```bash
# Start development server with hot reload
npm run dev

# Build for production 
npm run build

# Preview production build
npm run preview

# Install dependencies
npm install
```

The development server runs on port 3000 and opens to `/production/index.html` by default.

## Project Architecture

Gentelella is a Bootstrap 5 admin template built with Vite and modern JavaScript. The project uses a modular architecture with smart code splitting for optimal performance.

### Key Architecture Concepts

**Modular Loading System**: The template uses dynamic imports to load functionality only when needed:

- `main-core.js` (79KB) - Core essentials loaded on every page
- `modules/charts.js` (219KB) - Chart functionality loaded only on chart pages  
- `modules/forms.js` (200KB) - Form enhancements loaded only on form pages
- `modules/tables.js` - DataTables functionality loaded only on table pages
- `modules/dashboard.js` - Dashboard-specific widgets

**Entry Points**: Each HTML page has its own entry point defined in `vite.config.js` input configuration. The build system creates optimized bundles for each page.

**Global Library Management**: Libraries are made available globally through `window` and `globalThis` objects to maintain compatibility with legacy jQuery plugins.

### Directory Structure

```
src/
├── main-core.js          # Core bundle - essential libraries
├── main.js              # Full bundle - all libraries (legacy)
├── modules/             # Feature-specific modules
│   ├── charts.js        # Chart.js, Skycons, Sparklines
│   ├── forms.js         # Select2, DatePickers, Sliders
│   ├── tables.js        # DataTables functionality
│   └── dashboard.js     # Dashboard widgets
├── js/                  # Custom JavaScript
│   ├── init.js          # Page initialization
│   ├── sidebar.js       # Sidebar functionality
│   └── helpers/         # Utility functions
└── scss/                # Custom SASS files
    ├── custom.scss      # Main customizations
    └── *.scss          # Page-specific styles

production/              # HTML templates (42 pages)
├── index.html           # Main dashboard
├── form*.html          # Form pages
├── chart*.html         # Chart pages
└── *.html              # Other admin pages
```

### Code Splitting Strategy

The Vite configuration in `vite.config.js` defines manual chunks:

- `vendor-core`: jQuery, Bootstrap, Popper.js
- `vendor-charts`: Chart.js, ECharts, Leaflet
- `vendor-forms`: Select2, Ion Range Slider, Date pickers
- `vendor-ui`: jQuery UI, NProgress, DataTables
- `vendor-utils`: Day.js, Sparklines, Skycons

### Dynamic Module Loading

Use the global `loadModule()` function to conditionally load features:

```javascript
// Load charts module only if chart containers exist
if (document.querySelector('.chart-container')) {
  const charts = await loadModule('charts');
}
```

### Key Technologies

- **Build System**: Vite 6.3.5 with ES2022 target
- **CSS Framework**: Bootstrap 5.3.7 with custom SASS
- **Charts**: Chart.js 4.4.2 (Morris.js removed), ECharts 5.6.0
- **Forms**: Select2, Tempus Dominus date picker, Ion Range Slider
- **Tables**: DataTables with Bootstrap 5 styling
- **Icons**: Font Awesome 6.6.0
- **jQuery**: 3.6.1 (being phased out gradually)

### Performance Optimizations

The template achieves 90% smaller bundle sizes through:

- Dynamic imports for feature modules  
- Tree shaking of unused code
- Manual chunk splitting for optimal caching
- Terser minification with console/debugger removal
- Asset optimization with cache-busting

### Adding New Pages

1. Create HTML file in `production/` directory
2. Add entry to `vite.config.js` input object:
   ```javascript
   input: {
     'your-page': 'production/your-page.html'
   }
   ```
3. Reference appropriate modules in your page scripts
4. Use conditional loading for heavy features

### Testing

No specific test framework is configured. Check with the maintainer for preferred testing approach before adding tests.