🎮 FiveM React NUI Boilerplate - Memoria Compartida

---

📋 RESUMEN

Este es un boilerplate completo y funcional para desarrollar interfaces NUI en FiveM usando React moderno. La arquitectura está diseñada para ser escalable, mantenible y profesional.

✅ Estado Actual

• ✔️ Estructura de carpetas completa
• ✔️ Componentes React funcionales (Button, Input, Modal)
• ✔️ Stores Zustand (player, ui)
• ✔️ Comunicación Lua ↔ React funcionando
• ✔️ Build optimizado para producción
• ✔️ HUD, Menú e Inventario como ejemplos

---

🎯 PRÓXIMAS FASES (ROADMAP)

FASE 1: Sistema de Notificaciones (PRÓXIMO)

Objetivo: Crear sistema de notificaciones elegante

• Componente Notification.tsx
• Hook useNotification.ts
• Integración con eventos Lua
• Animaciones de entrada/salida
• Tipos de notificación (info, success, warning, error)

Archivos a crear:

src/components/UI/Notification.tsx
src/components/UI/Notification.module.scss
src/hooks/useNotification.ts
src/store/notificationStore.ts

Ejemplo de uso:

const { notify } = useNotification();
notify({ message: 'Dinero recibido', type: 'success' });

---

FASE 2: Sistema de Temas (Dark/Light Mode)

Objetivo: Implementar tema oscuro/claro

• Hook useTheme.ts
• Store para tema actual
• Variables SCSS dinámicas
• Persistencia en localStorage
• Toggle en settings

Archivos a crear:

src/hooks/useTheme.ts
src/store/themeStore.ts
src/styles/themes.scss
src/components/UI/ThemeToggle.tsx

---

FASE 3: Sistema de Datos (Data Management)

Objetivo: Gestión avanzada de estado global

• Normalización de datos
• Caché del cliente
• Sincronización con servidor
• Manejo de desconexiones
• Optimistic updates

Archivos a crear:

src/store/dataStore.ts
src/store/syncStore.ts
src/hooks/useSyncData.ts
src/utils/dataSync.ts

---

FASE 4: Integración con Framework (ESX/QB-Core)

Objetivo: Conectar con framework real

• ESX integration
• QB-Core integration
• Sistema de permisos
• Eventos del servidor
• Callbacks optimizados

Archivos a crear:

src/lib/frameworks/esx.ts
src/lib/frameworks/qbcore.ts
src/hooks/useFramework.ts
src/services/serverEvents.ts

---

FASE 5: Sistemas Complejos

Objetivo: Features avanzadas del juego

• Inventario dinámico
• Sistema de diálogos
• Formularios complejos
• Drag & drop
• Animations avanzadas

Componentes:

src/components/Features/AdvancedInventory/
src/components/Features/DialogSystem/
src/components/Features/Forms/
src/components/Features/DragDrop/

---

🏗️ ARQUITECTURA ACTUAL

Estructura de Carpetas

src/
├── assets/              # Imágenes y recursos
├── components/          # Componentes React
│   ├── UI/             # Componentes base (Button, Input, Modal)
│   ├── Layout/         # Estructura (Header, Container)
│   ├── Features/       # Features específicas (HUD, Menu, Inventory)
│   ├── App.tsx         # Raíz de la app
│   └── App.module.scss # Estilos raíz
├── lib/                # Librerías y utilidades
│   ├── constants.ts    # Constantes del proyecto
│   ├── css.ts          # Funciones de responsive (vh, vw, vmin)
│   ├── hooks.ts        # Hooks genéricos (useNuiEvent, useEvent)
│   ├── keys.ts         # Manejo de teclado
│   └── index.ts        # Exporta fetchNui()
├── hooks/              # Hooks personalizados
│   └── usePlayerStats.ts
├── store/              # Zustand stores
│   ├── playerStore.ts  # Estado del jugador
│   ├── uiStore.ts      # Estado de la UI
│   └── index.ts
├── styles/             # SCSS global
│   ├── variables.scss  # Variables de diseño
│   └── index.scss      # Estilos globales
├── types/              # Tipos TypeScript
│   └── index.ts        # Interfaces del proyecto
├── utils/              # Utilidades
│   ├── logger.ts       # Logger con Pino
│   └── validator.ts    # Validación con Zod
├── main.tsx            # Entry point
└── vite-env.d.ts       # Tipos de Vite

---

🔌 PATRONES DE COMUNICACIÓN

React → Lua (Enviar datos)

import { fetchNui } from '@/lib';

const response = await fetchNui('menu:action', { 
  action: 'heal' 
});

Lua → React (Recibir datos)

import { useNuiEvent } from '@/lib';

useNuiEvent('playerStats:update', (data) => {
  console.log('Stats:', data);
});

Callback Lua

RegisterNUICallback('menu:action', function(data, cb)
  -- Procesar
  cb({ success = true })
end)

---

📦 DEPENDENCIAS CLAVE

{
  "react": "^19.0.0",
  "typescript": "~5.7.2",
  "vite": "^6.0.3",
  "zustand": "^5.0.2",
  "sass": "^1.83.0",
  "pino": "^9.5.0",
  "zod": "^3.23.8",
  "babel-plugin-react-compiler": "^19.0.0-beta"
}

---

🎨 DESIGN SYSTEM

Colores (variables.scss)

• $color-primary: #646cff - Color principal
• $color-background: #242424 - Fondo
• $color-text: rgba(255, 255, 255, 0.87) - Texto

Espaciado

• $spacing-sm: 8px
• $spacing-md: 16px
• $spacing-lg: 24px

Tipografía

• Font: system-ui, Avenir, Helvetica
• Sizes: sm (0.875rem), base (1rem), lg (1.25rem)

---

🛠️ SCRIPTS DISPONIBLES

npm run dev      # Desarrollo (Vite dev server)
npm run build    # Build producción (genera web/dist/)
npm run preview  # Preview del build
npm run lint     # Lint con ESLint

---

📝 ESTÁNDARES DE CÓDIGO

Componentes React

// ✅ CORRECTO
interface ButtonProps {
  children: React.ReactNode;
  onClick?: () => void;
}

export const Button: React.FC<ButtonProps> = ({ children, onClick }) => {
  return <button onClick={onClick}>{children}</button>;
};

SCSS Modules

// ✅ Importar variables
@import '@/styles/variables';

// ✅ Usar módulos
.button {
  background-color: $color-primary;
  padding: $spacing-md;
}

Imports

// ✅ Usar alias @
import { Button } from '@/components/UI';
import { usePlayerStore } from '@/store';

// ❌ Evitar
import Button from '../../components/UI/Button';

---

🚀 CÓMO EMPEZAR EN NUEVAS FUNCIONALIDADES

Template para nuevo componente

1. Crear carpeta: src/components/Features/[NombreFeature]/
2. Crear archivos:
   - [NombreFeature].tsx
   - [NombreFeature].module.scss
   - index.ts (exportar el componente)
3. Copiar imports estándar
4. Usar stores y hooks según sea necesario

Template para nuevo hook

1. Crear archivo: src/hooks/use[NombreHook].ts
2. Exportar en: src/hooks/index.ts
3. Usar con: import { use[NombreHook] } from '@/hooks'

Template para nuevo store

1. Crear archivo: src/store/[nombreStore].ts
2. Exportar en: src/store/index.ts
3. Usar con: import { use[NombreStore] } from '@/store'

---

⚠️ PROBLEMAS COMUNES Y SOLUCIONES

Error: Cannot find module '@/components/UI'

Causa: Falta index.ts o archivo tiene mayúscula Solución:

• Verificar que src/components/UI/index.ts exista
• Renombrar Index.ts → index.ts (minúscula)

Error: baseUrl is deprecated

Causa: TypeScript 6.0+ deprecó baseUrl Solución: Es solo un warning, no afecta funcionamiento

Build falla con tsc error

Causa: Script de build incluye type-checking Solución: Usar solo vite build sin tsc -b

Imports relativos no funcionan

Causa: Rutas mal calculadas Solución: Usar alias @/ en lugar de ../../../

---

📚 RECURSOS ÚTILES

• Vite Docs
• React 19 Docs
• Zustand Docs
• SCSS Documentation
• TypeScript Handbook

---

💾 CHECKLIST PARA NUEVOS DESARROLLADORES

Antes de empezar a desarrollar:

• Clonar el repositorio
• npm install
• npm run dev funciona
• VSCode muestra 0 errores TypeScript
• Entender la estructura de carpetas
• Leer esta guía
• Revisar componentes existentes como referencia
• Practicar con una pequeña feature
• Consultar estándares de código antes de commitear

---

🎓 APRENDIZAJE PROGRESIVO

Nivel 1: Básico (1-2 semanas)

• Entiende la estructura
• Crea componentes simples (Button, Input)
• Practica con props y hooks

Nivel 2: Intermedio (2-4 semanas)

• Crea features completas (HUD, Menu)
• Usa stores con Zustand
• Integra comunicación Lua-React

Nivel 3: Avanzado (4+ semanas)

• Diseña arquitectura de features complejas
• Optimiza performance
• Implementa patrones avanzados
• Lidera desarrollo de nuevas fases

---

🔄 ACTUALIZACIONES PENDIENTES

• Documentar fase de notificaciones
• Documentar integración ESX/QB
• Video tutorial de setup
• Testing setup (Jest + React Testing Library)
• CI/CD configuration