Installation Guide

Complete installation and setup instructions for Gentelella Admin Template

Table of contents

  1. System Requirements
    1. Prerequisites
    2. Browser Support
  2. Installation Methods
    1. Method 1: Git Clone (Recommended)
    2. Method 2: Download ZIP
    3. Method 3: npm Package
    4. Method 4: Yarn Package
    5. Method 5: Bower (Legacy)
  3. Project Structure
  4. Development Commands
    1. Basic Commands
    2. Advanced Commands
  5. Configuration
    1. Environment Setup
    2. Vite Configuration
    3. SASS Configuration
  6. Verification
    1. Check Installation
    2. Test All Pages
    3. Performance Check
  7. Troubleshooting
    1. Common Issues
      1. 1. Node.js Version Issues
      2. 2. Port Already in Use
      3. 3. SASS Compilation Errors
      4. 4. Module Not Found
      5. 5. Build Failures
    2. Getting Help
  8. Next Steps

System Requirements

Prerequisites

Before installing Gentelella, ensure you have the following installed:

  • Node.js (v16 or higher) - Download here
  • npm (comes with Node.js) or yarn package manager
  • Git (for cloning the repository)
  • A modern code editor (VS Code recommended)

Browser Support

Gentelella supports all modern browsers:

Browser Minimum Version
Chrome 88+
Firefox 85+
Safari 14+
Edge 88+
Opera 74+

Note: Internet Explorer is not supported.

Installation Methods

This is the recommended method for development and customization:

# Clone the repository
git clone https://github.com/puikinsh/gentelella.git

# Navigate to the project directory
cd gentelella

# Install dependencies
npm install

# Start the development server
npm run dev

Your development server will be running at http://localhost:3000

Method 2: Download ZIP

  1. Visit GitHub repository
  2. Click “Code” → “Download ZIP”
  3. Extract the ZIP file
  4. Open terminal in the extracted folder
  5. Run npm install
  6. Run npm run dev

Method 3: npm Package

Install as a dependency in your existing project:

npm install gentelella --save

Method 4: Yarn Package

If you prefer Yarn:

yarn add gentelella

Method 5: Bower (Legacy)

For legacy projects using Bower:

bower install gentelella --save

Project Structure

After installation, your project structure will look like this:

gentelella/
├── 📁 docs/                   # Documentation files
├── 📁 production/              # HTML templates & assets
│   ├── 📄 index.html          # Main dashboard
│   ├── 📄 form.html           # Form examples
│   ├── 📄 tables.html         # Table examples
│   ├── 📄 charts.html         # Chart examples
│   ├── 📄 [38 more pages]     # Complete admin coverage
│   └── 📁 images/             # Image assets
├── 📁 src/                    # Source files
│   ├── 📄 main-core.js        # Core bundle (79KB)
│   ├── 📄 main.js             # Full bundle (779KB)
│   ├── 📄 main.scss           # Styles entry point
│   ├── 📁 js/                 # Custom JavaScript
│   ├── 📁 scss/               # Custom SASS files
│   └── 📁 modules/            # Smart loading modules
│       ├── 📄 charts.js       # Chart libraries (219KB)
│       ├── 📄 forms.js        # Form enhancements (200KB)
│       ├── 📄 tables.js       # DataTables functionality
│       ├── 📄 dashboard.js    # Dashboard widgets
│       └── 📄 utils.js        # Utility functions
├── 📁 dist/                   # Production build output
├── 📁 scripts/                # Build & optimization tools
├── 📁 vendors/                # Third-party libraries
├── 📄 vite.config.js          # Vite configuration
├── 📄 package.json            # Dependencies & scripts
└── 📄 README.md               # Basic documentation

Development Commands

Basic Commands 

# Start development server with hot reload
npm run dev

# Build for production
npm run build

# Preview production build locally
npm run preview

Advanced Commands 

# Build with bundle analysis
npm run build:analyze

# Performance optimization analysis
npm run optimize

# SASS compilation only
npm run sass:watch

# JavaScript linting
npm run lint

# Code formatting
npm run format

Configuration

Environment Setup

  1. Development Environment 
    npm run dev
    • Hot reload enabled
    • Source maps available
    • All modules loaded for development
  2. Production Environment 
    npm run build
npm run preview
    • Optimized bundles
    • Minified assets
    • Smart code splitting

Vite Configuration

The template includes an optimized vite.config.js with:

  • Entry Points: All 42 HTML files configured
  • Code Splitting: Automatic vendor/app separation
  • Asset Optimization: Images, fonts, and static files
  • Development Features: Hot reload, source maps
  • Production Optimizations: Minification, compression

SASS Configuration

SASS is configured in src/main.scss:

// Modern @use syntax (recommended)
@use "bootstrap/scss/bootstrap";
@use "./scss/custom.scss";

// Legacy @import syntax (deprecated but still works)
// @import "bootstrap/scss/bootstrap";
// @import "./scss/custom.scss";

Verification

Check Installation

After installation, verify everything is working:

  1. Start the development server: 
    npm run dev

  2. Open your browser and navigate to http://localhost:3000

  3. You should see the Gentelella dashboard

Test All Pages

Navigate through different pages to ensure all modules load correctly:

  • Dashboard pages (index.html, index2.html, index3.html)
  • Form pages (form.html, form_advanced.html, form_validation.html)
  • Table pages (tables.html, tables_dynamic.html)
  • Chart pages (chartjs.html, chartjs2.html, morisjs.html)

Performance Check

Run the optimization analysis:

npm run optimize

This will show you:

  • Bundle sizes
  • Loading times
  • Optimization recommendations

Troubleshooting

Common Issues

1. Node.js Version Issues

Error: npm ERR! engine Unsupported engine

Solution: Update Node.js to version 16 or higher:

# Check current version
node --version

# Update Node.js from https://nodejs.org/

2. Port Already in Use

Error: Port 3000 is already in use

Solution: Either stop the conflicting process or use a different port:

# Use different port
npm run dev -- --port 3001

3. SASS Compilation Errors

Error: SASS deprecation warnings

Solution: These are mainly from Bootstrap internal files and can be safely ignored. Our project code uses modern SASS syntax.

4. Module Not Found

Error: Cannot resolve module

Solution: Clear cache and reinstall:

# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall dependencies
npm install

5. Build Failures

Error: Build process fails

Solution: Check for file permission issues and ensure all dependencies are installed:

# Clear cache
npm cache clean --force

# Reinstall
npm install

# Try building again
npm run build

Getting Help

If you encounter issues not covered here:

  1. Check GitHub Issues: github.com/puikinsh/gentelella/issues
  2. Create New Issue: Provide detailed error messages and system information
  3. Community Support: Join discussions on GitHub
  4. Documentation: Check other sections of this documentation

Next Steps

After successful installation:

  1. Configuration Guide - Customize the template
  2. Components Overview - Explore available components
  3. Performance Guide - Optimize your build
  4. Customization - Add your own styles and features

💡 Pro Tip: Use npm run dev during development for the best experience with hot reload and source maps. Only use npm run build when you’re ready to deploy to production.