Installation guide

This guide provides comprehensive instructions for installing, configuring, and deploying MKing Admin.

Prerequisites

Required software

Ensure you have the following installed before proceeding:

Node.js and npm

Node.js version 16.x or higher is recommended.Verify your installation:

node --version
npm --version

Download from nodejs.org if needed.

Git

Git for version control and cloning the repository.

git --version

Download from git-scm.com if needed.

Code editor

A modern code editor like Visual Studio Code is recommended for TypeScript support and IntelliSense.

System requirements

Operating System: Windows 10+, macOS 10.15+, or Linux
RAM: Minimum 4GB (8GB recommended for development)
Disk Space: At least 500MB for dependencies and build artifacts

Installation steps

1. Clone the repository

Clone the MKing Admin repository to your local machine:

git clone <your-repository-url>
cd mking

2. Install dependencies

MKing Admin uses npm for package management. Install all dependencies:

npm install

This will install the following key dependencies (from package.json:12-58):

Core dependencies

[email protected] - React library
[email protected] - React DOM rendering
[email protected] - TypeScript compiler
[email protected] - Build tool and dev server

UI framework

@mui/[email protected] - Material-UI components
@mui/[email protected] - Material Design icons
@emotion/[email protected] - CSS-in-JS styling
@emotion/[email protected] - Styled components

State management

@reduxjs/[email protected] - Redux state management
[email protected] - React bindings for Redux
[email protected] - Persist Redux state
[email protected] - Lightweight state management

Routing & forms

[email protected] - Client-side routing
[email protected] - Form handling
[email protected] - Schema validation

Data & visualization

[email protected] - Advanced data grids
[email protected] - Charts and graphs
@fullcalendar/[email protected] - Calendar component

Utilities

[email protected] - HTTP client
[email protected] - JWT token decoding
[email protected] - Date utilities
[email protected] - Utility functions

The complete dependency list includes over 40 packages. Installation may take 2-5 minutes depending on your internet connection.

3. Environment configuration

Create a .env file in the project root:

cp .env.example .env

Configure the environment variables:

.env

# Environment mode (develop, staging, production)
VITE_APP_ENV=develop

# API base URL
VITE_BASE_URL=http://localhost:3008/api

# Optional: Production URLs
# VITE_GL_PRUEBAS=https://pruebas.garantia.mx
# VITE_GL_PRODUCCION=https://app.garantia.mx

Environment variables explained

Variable	Description	Example
`VITE_APP_ENV`	Application environment	`develop`, `production`
`VITE_BASE_URL`	Backend API base URL	`http://localhost:3008/api`
`VITE_GL_PRUEBAS`	Testing environment URL	`https://pruebas.garantia.mx`
`VITE_GL_PRODUCCION`	Production environment URL	`https://app.garantia.mx`

Never commit your .env file to version control. It’s already included in .gitignore by default.

4. TypeScript configuration

MKing Admin uses TypeScript with strict type checking. The configuration is already set up in tsconfig.json:2-18:

{
  "compilerOptions": {
    "target": "ESNext",
    "lib": ["DOM", "DOM.Iterable", "ESNext"],
    "jsx": "react-jsx",
    "module": "ESNext",
    "moduleResolution": "Node",
    "strict": true,
    "esModuleInterop": false,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "noEmit": true
  }
}

Key TypeScript features enabled:

Strict mode: Enhanced type checking
JSX: React JSX transform
ES Modules: Modern module system

5. Development server configuration

The Vite development server is configured in vite.config.ts with the following settings:

server: {
  host: '0.0.0.0',      // Allow local network access
  port: 5000,           // Development port
  hmr: {
    host: 'localhost',
    overlay: true,      // Show errors as overlay
    timeout: 30000
  },
  proxy: {
    '/api': {
      target: 'http://localhost:3333',
      changeOrigin: true,
      secure: false
    }
  },
  watch: {
    usePolling: true    // For Docker/VM environments
  }
}

The proxy configuration routes all /api requests to http://localhost:3333, allowing seamless communication with the backend API during development.

Running the application

Development mode

Start the development server with hot module replacement:

npm run dev

The application will be available at:

Local: http://localhost:5000
Network: http://<your-ip>:5000

Type checking

Run TypeScript type checking without emitting files:

npm run typecheck

Production build

Create an optimized production build:

npm run build

The build output will be in the dist/ directory.

Preview production build

Preview the production build locally:

npm run preview

Project structure

After installation, your project structure will look like this:

mking/
├── src/
│   ├── Main.tsx              # Application entry point
│   ├── auth/                 # Authentication module
│   ├── core/                 # Core application wrapper
│   ├── pages/                # Feature pages
│   │   ├── Calendar/         # Calendar & scheduling
│   │   ├── Employees/        # Employee management
│   │   ├── Product/          # Product catalog
│   │   ├── Quotations/       # Quotation generation
│   │   ├── Users/            # User management
│   │   ├── Roles/            # Role management
│   │   ├── client/           # Client CRM
│   │   └── catalogs/         # Various catalogs
│   ├── router/               # Route definitions
│   ├── services/             # API services
│   ├── store/                # State management
│   │   ├── authStore.ts      # Zustand auth store
│   │   └── pageTitleStore.ts # Page title state
│   ├── theme/                # MUI theme config
│   ├── utils/                # Utility functions
│   └── assets/               # Static assets
├── index.html                # HTML entry point
├── vite.config.ts            # Vite configuration
├── tsconfig.json             # TypeScript config
├── package.json              # Dependencies
└── .env                      # Environment variables

Authentication architecture

MKing Admin uses Zustand for authentication state management (from src/store/authStore.ts:11-33):

interface AuthState {
  user: User | null;
  permissions: string[];
  isAuthenticated: boolean;
  setAuth: (user: User, permissions: string[]) => void;
  clearAuth: () => void;
}

The authentication store manages:

User profile data
Permission-based access control
Authentication state across the application

Backend API setup

MKing Admin requires a backend API to function properly. Ensure your backend is running before starting the frontend application.

The application expects:

Backend API running on http://localhost:3333 (default)
API endpoints available at /api/*
JWT-based authentication

If your backend runs on a different port, update:

.env: Change VITE_BASE_URL
vite.config.ts: Update proxy target in server configuration

Troubleshooting

Installation issues

Problem: npm install fails with permission errors Solution: Try using sudo (Linux/Mac) or run as administrator (Windows), or fix npm permissions:

sudo chown -R $USER:$USER ~/.npm

Build issues

Problem: TypeScript compilation errors Solution: Ensure you’re using TypeScript 5.7.2:

npm list typescript

Problem: Module resolution errors Solution: Clear cache and reinstall:

rm -rf node_modules package-lock.json
npm install

Runtime issues

Problem: API requests failing Solution:

Verify backend is running on correct port
Check CORS configuration on backend
Verify VITE_BASE_URL in .env
Check proxy configuration in vite.config.ts

Problem: Authentication not persisting Solution: Check browser localStorage/sessionStorage. Redux Persist stores authentication state locally.

Next steps

After successful installation:

Review the application structure in src/
Explore the authentication flow in src/auth/
Understand state management in src/store/
Customize the Material-UI theme in src/theme/
Start building your features in src/pages/

For testing, MKing Admin includes Vitest configuration. Run tests with npm test (testing setup is in src/vitest.setup.ts).

Getting Started

Core Features

User Management

Configuration

Installation guide

Installation guide

Prerequisites

Required software

System requirements

Installation steps

1. Clone the repository

2. Install dependencies

Core dependencies

UI framework

State management

Routing & forms

Data & visualization

Utilities

3. Environment configuration

Environment variables explained

4. TypeScript configuration

5. Development server configuration

Running the application

Development mode

Type checking

Production build

Preview production build

Project structure

Authentication architecture

Backend API setup

Troubleshooting

Installation issues

Build issues

Runtime issues

Next steps

Build docs developers (and LLMs) love

Getting Started

Core Features

User Management

Configuration

​Installation guide

​Prerequisites

​Required software

​System requirements

​Installation steps

​1. Clone the repository

​2. Install dependencies

​Core dependencies

​UI framework

​State management

​Routing & forms

​Data & visualization

​Utilities

​3. Environment configuration

​Environment variables explained

​4. TypeScript configuration

​5. Development server configuration

​Running the application

​Development mode

​Type checking

​Production build

​Preview production build

​Project structure

​Authentication architecture

​Backend API setup

​Troubleshooting

​Installation issues

​Build issues

​Runtime issues

​Next steps

Build docs developers (and LLMs) love

Installation guide

Prerequisites

Required software

System requirements

Installation steps

1. Clone the repository

2. Install dependencies

Core dependencies

UI framework

State management

Routing & forms

Data & visualization

Utilities

3. Environment configuration

Environment variables explained

4. TypeScript configuration

5. Development server configuration

Running the application

Development mode

Type checking

Production build

Preview production build

Project structure

Authentication architecture

Backend API setup

Troubleshooting

Installation issues

Build issues

Runtime issues

Next steps