Installation Guide

System Requirements

Before installing GIMA, ensure your system meets these requirements:

Required

Node.js: Version 20.x or higher
Package Manager: npm (included with Node.js), pnpm, or yarn
Git: For cloning the repository
Operating System: Windows 10+, macOS 10.15+, or Linux

Installation Steps

Follow these detailed steps to install GIMA:

Install Node.js

If you don’t have Node.js 20+ installed:Using nvm (Recommended):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 20
nvm install 20
nvm use 20

Direct Download: Download from nodejs.org and install the LTS version (20.x or higher).Verify Installation:

node --version  # Should show v20.x.x or higher
npm --version   # Should show 10.x.x or higher

Clone the Repository

Clone the GIMA project from GitHub:

git clone https://github.com/GonzalezCesar/gima-project.git
cd gima-project

Alternative: Download ZIPIf you don’t have Git:

Visit github.com/GonzalezCesar/gima-project
Click “Code” → “Download ZIP”
Extract the archive and navigate to the folder

Install Dependencies

Install all required packages using your preferred package manager:

npm install

This installs the following key dependencies:Core Framework:

[email protected] - React framework
[email protected] - React library
[email protected] - React DOM renderer
typescript@^5 - TypeScript support

UI & Styling:

tailwindcss@^4 - Utility-first CSS framework
lucide-react@^0.562.0 - Icon library
clsx@^2.1.1 - Conditional class names
tailwind-merge@^3.4.0 - Merge Tailwind classes
class-variance-authority@^0.7.1 - Component variants

Development Tools:

@tailwindcss/postcss@^4.1.18 - PostCSS plugin
eslint@^9 - Code linting
[email protected] - React optimization

Installation may take 2-5 minutes depending on your internet connection.

Verify Installation

Ensure everything is installed correctly:

# Check if node_modules exists
ls node_modules

# Verify Next.js is installed
npx next --version

# Check TypeScript
npx tsc --version

You should see version numbers for each command without errors.

Environment Configuration

GIMA uses environment variables for configuration:

Create Environment File

Currently, GIMA doesn’t require a .env file for basic development, but you may want to create one for custom configuration:

touch .env.local

.env.local is automatically ignored by Git and is the recommended file for local development settings.

Configure Environment Variables (Optional)

Add any custom environment variables to .env.local:

.env.local

# Development settings
NODE_ENV=development

# Custom port (optional)
PORT=3000

# API endpoints (when implementing backend)
# NEXT_PUBLIC_API_URL=http://localhost:8000/api

# Authentication (when implementing auth)
# NEXTAUTH_SECRET=your-secret-key-here
# NEXTAUTH_URL=http://localhost:3000

Never commit .env.local or any file containing secrets to version control. These files are in .gitignore by default.

Development Server Setup

Now you’re ready to run GIMA:

Start Development Server

Launch the Next.js development server:

npm run dev

You should see output similar to:

▲ Next.js 16.1.1
- Local:        http://localhost:3000
- Environments: .env.local

✓ Starting...
✓ Ready in 2.3s

Access the Application

Open your browser and navigate to:

http://localhost:3000

You’ll be automatically redirected to the login page (/auth/login).

Verify All Pages Load

Test that key pages are accessible:

Login: http://localhost:3000/auth/login
Dashboard: http://localhost:3000/dashboard (after login)
Configuration: http://localhost:3000/configuracion
Reports: http://localhost:3000/reportes

Hot Module Replacement (HMR) is enabled - changes to your code will automatically refresh the browser.

Production Build

To create a production-optimized build:

Build the Application

Create an optimized production build:

npm run build

This will:

Compile TypeScript to JavaScript
Optimize React components with React Compiler
Bundle and minify all code
Generate static pages where possible
Create optimized production assets

Output will be in the .next directory.

Start Production Server

Run the production build:

npm run start

The production server will start on http://localhost:3000 by default.

Test Production Build

Verify that:

Pages load faster than in development
No console errors appear
All features work as expected
Static assets load correctly

Project Structure

After installation, your project structure will look like:

gima-project/
├── .git/                     # Git repository
├── .next/                    # Next.js build output (generated)
├── node_modules/             # Dependencies (generated)
├── public/                   # Static assets
│   ├── logo-gima.png        # Application logo
│   └── fonts/               # Custom fonts
│       ├── font-microgramma.otf
│       └── font-archivo.ttf
├── src/                      # Source code
│   ├── app/                 # Next.js App Router
│   │   ├── auth/login/      # Login page
│   │   ├── dashboard/       # Dashboard pages
│   │   ├── configuracion/   # Configuration pages
│   │   ├── reportes/        # Reports
│   │   ├── asistencia/      # Support
│   │   ├── layout.tsx       # Root layout
│   │   ├── page.tsx         # Home (redirects to login)
│   │   └── globals.css      # Global styles
│   ├── components/          # React components
│   │   ├── layout/          # MainLayout, DashboardHeader
│   │   ├── dashboard/       # StatCard, ChartPlaceholder
│   │   ├── configuracion/   # TablaDeCategorias
│   │   ├── ui/              # Reusable UI components
│   │   └── user/            # User-related components
│   ├── types/               # TypeScript definitions
│   │   ├── index.ts
│   │   └── user.ts
│   ├── data/                # Static data
│   │   └── categories.ts
│   ├── services/            # API services
│   │   └── dataService.ts
│   ├── lib/                 # Utilities
│   └── utils/               # Helper functions
├── .gitignore               # Git ignore rules
├── components.json          # Shadcn UI config
├── eslint.config.mjs        # ESLint configuration
├── next.config.ts           # Next.js configuration
├── package.json             # Dependencies and scripts
├── postcss.config.mjs       # PostCSS configuration
├── tsconfig.json            # TypeScript configuration
└── README.md                # Project readme

Configuration Files

Key configuration files and their purposes:

next.config.ts

Next.js configuration with React Compiler enabled:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  reactCompiler: true,  // Enables React 19 compiler
};

export default nextConfig;

tsconfig.json

TypeScript configuration with path aliases:

{
  "compilerOptions": {
    "target": "ES2017",
    "jsx": "react-jsx",
    "paths": {
      "@/*": ["./src/*"]  // Import alias for src/
    }
  }
}

This allows imports like import { MainLayout } from "@/components/layout/MainLayout"

components.json

Shadcn UI configuration:

{
  "style": "new-york",
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}

Troubleshooting

Common installation issues and solutions:

Node Version Errors

Error: error [email protected]: The engine "node" is incompatible with this moduleSolution:

Check your Node.js version:
```
node --version
```

If below v20, upgrade Node.js:

# Using nvm
nvm install 20
nvm use 20
nvm alias default 20

Retry installation:

rm -rf node_modules package-lock.json
npm install

Port Already in Use

Error: Port 3000 is already in useSolution 1 - Use Different Port:

PORT=3001 npm run dev

Solution 2 - Kill Process on Port 3000:

# On macOS/Linux
lsof -ti:3000 | xargs kill -9

# On Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process

EACCES Permission Errors

Error: EACCES: permission deniedSolution: Don’t use sudo with npm. Instead, fix npm permissions:

# Create a directory for global packages
mkdir ~/.npm-global

# Configure npm to use this directory
npm config set prefix '~/.npm-global'

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH

# Reload shell config
source ~/.bashrc  # or source ~/.zshrc

Then retry installation.

Module Not Found After Installation

Error: Module not found: Can't resolve '@/components/...'Solution:

Ensure you’re in the project root directory
Delete .next and node_modules:
```
rm -rf .next node_modules
```
Clear npm cache:
```
npm cache clean --force
```
Reinstall:
```
npm install
npm run dev
```

TypeScript Compilation Errors

Error: Various TypeScript errors during buildSolution:

Verify TypeScript version:
```
npx tsc --version  # Should be 5.x
```
Delete TypeScript cache:
```
rm -rf .next tsconfig.tsbuildinfo
```
Restart the dev server:
```
npm run dev
```
If errors persist, check for type errors:
```
npx tsc --noEmit
```

Build Fails with Out of Memory

Error: JavaScript heap out of memorySolution: Increase Node.js memory limit:

# Temporary (single command)
NODE_OPTIONS="--max-old-space-size=4096" npm run build

# Permanent (add to package.json scripts)
{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
  }
}

Slow Installation on Windows

Issue: npm install takes very long on WindowsSolution:

Disable Windows Defender real-time scanning for the project folder temporarily
Use pnpm instead (faster on Windows):
```
npm install -g pnpm
pnpm install
```

Or enable package-lock optimizations:

npm config set package-lock true
npm ci  # Instead of npm install

Next Steps

Now that GIMA is installed:

Quickstart Guide

Take a quick tour of GIMA’s main features

Configuration

Configure GIMA for your organization

API Reference

Learn how to use GIMA components

Configuration

Configure GIMA for your needs

Getting Help

If you encounter issues not covered here:

Check the Quickstart Guide for basic usage
Review Next.js documentation
Report bugs on GitHub Issues
Access in-app support through the Asistencia module

Get Started

Core Features

Configuration

Guides

Installation Guide

System Requirements

Required

Recommended

Installation Steps

Environment Configuration

Development Server Setup

Production Build

Project Structure

Configuration Files

next.config.ts

tsconfig.json

components.json

Troubleshooting

Next Steps

Quickstart Guide

Configuration

API Reference

Configuration

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Guides

​System Requirements

​Required

​Recommended

​Installation Steps

​Environment Configuration

​Development Server Setup

​Production Build

​Project Structure

​Configuration Files

​next.config.ts

​tsconfig.json

​components.json

​Troubleshooting

​Next Steps

Quickstart Guide

Configuration

API Reference

Configuration

​Getting Help

Build docs developers (and LLMs) love

System Requirements

Required

Recommended

Installation Steps

Environment Configuration

Development Server Setup

Production Build

Project Structure

Configuration Files

next.config.ts

tsconfig.json

components.json

Troubleshooting

Next Steps

Getting Help