workspace/projects/gamilit/docs/95-guias-desarrollo/frontend/SETUP-DEVELOPMENT.md

Setup de Desarrollo Frontend

Versión: 1.0.0 Última Actualización: 2025-11-28 Aplica a: apps/frontend/

---

Requisitos Previos

• Node.js v18+ (recomendado v20 LTS)
• npm v9+ o pnpm
• Git
• Backend de GAMILIT corriendo (ver ../backend/SETUP-DEVELOPMENT.md)

---

Instalación Inicial

1. Clonar Repositorio

git clone <repository-url>
cd gamilit

2. Instalar Dependencias

# Desde la raíz del monorepo
npm install

3. Configurar Variables de Entorno

# Copiar template
cp apps/frontend/.env.example apps/frontend/.env

# Editar con tus valores
nano apps/frontend/.env

Variables Requeridas

# API Backend
VITE_API_URL=http://localhost:3000/api/v1

# WebSocket
VITE_WS_URL=http://localhost:3000

# Environment
VITE_ENV=development

---

Ejecutar Frontend

Modo Desarrollo (con hot-reload)

# Desde raíz del monorepo
npm run dev:frontend

# O desde apps/frontend
cd apps/frontend
npm run dev

El servidor de desarrollo estará en: http://localhost:5173

Modo Producción (build)

npm run build:frontend

# Previsualizar build
npm run preview:frontend

---

Verificar Instalación

1. Abrir http://localhost:5173 en el navegador
2. Verificar que la página de login carga correctamente
3. Verificar conexión con backend (network tab)

---

Estructura del Proyecto

apps/frontend/
├── public/                  # Archivos estáticos
│   ├── favicon.ico
│   └── assets/
├── src/
│   ├── main.tsx            # Entry point
│   ├── App.tsx             # Root component
│   ├── router/             # React Router config
│   │   └── index.tsx
│   ├── features/           # Feature modules
│   │   ├── auth/
│   │   ├── dashboard/
│   │   ├── exercises/
│   │   ├── gamification/
│   │   └── ...
│   ├── shared/             # Shared code
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── lib/
│   │   ├── utils/
│   │   └── types/
│   └── styles/             # Global styles
│       └── globals.css
├── index.html
├── vite.config.ts
├── tailwind.config.js
├── tsconfig.json
└── package.json

---

Scripts Disponibles

Script	Descripción
npm run dev	Desarrollo con hot-reload
npm run build	Build para producción
npm run preview	Previsualizar build
npm run test	Ejecutar tests
npm run test:watch	Tests en modo watch
npm run test:coverage	Tests con coverage
npm run lint	Ejecutar ESLint
npm run format	Formatear con Prettier
npm run type-check	Verificar tipos TypeScript

---

Configuración de IDE

VS Code Extensions Recomendadas

• ESLint
• Prettier
• Tailwind CSS IntelliSense
• ES7+ React/Redux/React-Native snippets
• Auto Rename Tag
• Path Intellisense

Settings Recomendadas

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "tailwindCSS.includeLanguages": {
    "typescript": "javascript",
    "typescriptreact": "javascript"
  },
  "files.associations": {
    "*.css": "tailwindcss"
  }
}

---

Debugging

React DevTools

1. Instalar extensión de Chrome: React DevTools
2. Abrir DevTools → Components tab

React Query DevTools

Ya incluido en desarrollo. Aparece un botón flotante en la esquina inferior derecha.

VS Code Debugger

Crear .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Launch Chrome",
      "url": "http://localhost:5173",
      "webRoot": "${workspaceFolder}/apps/frontend/src"
    }
  ]
}

---

Desarrollo con Backend

Proxy Configuration

Si necesitas proxy para evitar CORS en desarrollo:

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
      },
    },
  },
});

Ejecutar Frontend + Backend

# Desde raíz del monorepo
npm run dev  # Ejecuta ambos en paralelo

# O en terminales separadas
npm run dev:backend
npm run dev:frontend

---

Testing

Ejecutar Tests

# Todos los tests
npm run test

# Con UI de Vitest
npm run test:ui

# Coverage
npm run test:coverage

Escribir Tests

// features/gamification/components/__tests__/RankBadge.test.tsx
import { render, screen } from '@testing-library/react';
import { RankBadge } from '../RankBadge';

describe('RankBadge', () => {
  it('renders rank name', () => {
    const rank = { name: 'Ajaw', iconUrl: '/icons/ajaw.png' };
    render(<RankBadge rank={rank} />);

    expect(screen.getByText('Ajaw')).toBeInTheDocument();
  });
});

---

Troubleshooting

Error: Module not found

# Reinstalar dependencias
rm -rf node_modules
npm install

Error: Port 5173 already in use

# Encontrar proceso
lsof -i :5173

# Matar proceso
kill -9 <PID>

Error: CORS

• Verificar que VITE_API_URL apunta al backend correcto
• Verificar que el backend tiene CORS configurado

Error: TypeScript

# Verificar tipos
npm run type-check

Hot reload no funciona

• Verificar que no hay errores de TypeScript
• Reiniciar el servidor de desarrollo
• Limpiar cache de Vite: rm -rf node_modules/.vite

---

Desarrollar Nuevas Features

1. Crear Estructura

mkdir -p src/features/nueva-feature/{components,hooks,services,types}

2. Crear Archivos Base

// src/features/nueva-feature/index.ts
export { MiComponente } from './components/MiComponente';
export { useMiHook } from './hooks/useMiHook';

3. Registrar Rutas

// src/router/index.tsx
import { NuevaFeaturePage } from '@/features/nueva-feature/pages/NuevaFeaturePage';

const routes = [
  // ...existing routes
  { path: '/nueva-feature', element: <NuevaFeaturePage /> },
];

---

Ver También

• ESTRUCTURA-FEATURES.md - Estructura de features
• STATE-MANAGEMENT.md - Zustand y React Query
• API-INTEGRATION.md - Conexión con backend
• ../DEV-SERVERS.md - Servidores de desarrollo