marnixGeerkens/rocketlauncher-claude-code

Guías de Desarrollo Frontend

Propósito

Guía completa para el desarrollo moderno con React, enfatizando la obtención de datos basada en Suspense, lazy loading, organización adecuada de archivos y optimización del rendimiento.

Cuándo Usar Esta Skill

• Crear nuevos componentes o páginas
• Construir nuevas funcionalidades
• Obtener datos con TanStack Query
• Configurar enrutamiento con TanStack Router
• Estilizar componentes con MUI v7
• Optimizar el rendimiento
• Organizar código frontend
• Mejores prácticas de TypeScript

---

Inicio Rápido

Lista de Verificación para Nuevos Componentes

¿Creando un componente? Sigue esta lista:

• Usa el patrón React.FC<Props> con TypeScript
• Carga diferida si es un componente pesado: React.lazy(() => import())
• Envuelve en <SuspenseLoader> para estados de carga
• Usa useSuspenseQuery para la obtención de datos
• Importa alias: @/, ~types, ~components, ~features
• Estilos: En línea si <100 líneas, archivo separado si >100 líneas
• Usa useCallback para manejadores de eventos pasados a hijos
• Exportación por defecto al final
• Sin retornos tempranos con spinners de carga
• Usa useMuiSnackbar para notificaciones al usuario

Lista de Verificación para Nuevas Funcionalidades

¿Creando una funcionalidad? Configura esta estructura:

• Crea el directorio features/{nombre-funcionalidad}/
• Crea subdirectorios: api/, components/, hooks/, helpers/, types/
• Crea el archivo de servicio API: api/{nombreFuncionalidad}Api.ts
• Configura los tipos TypeScript en types/
• Crea la ruta en routes/{nombre-funcionalidad}/index.tsx
• Carga diferida de los componentes de la funcionalidad
• Usa límites de Suspense
• Exporta la API pública desde index.ts de la funcionalidad

---

Referencia Rápida de Alias de Importación

Alias	Resuelve a	Ejemplo
@/	src/	import { apiClient } from '@/lib/apiClient'
~types	src/types	import type { User } from '~types/user'
~components	src/components	import { SuspenseLoader } from '~components/SuspenseLoader'
~features	src/features	import { authApi } from '~features/auth'

Definido en: vite.config.ts líneas 180-185

---

Chuleta de Importaciones Comunes

// React y Carga Diferida
import React, { useState, useCallback, useMemo } from 'react';
const Heavy = React.lazy(() => import('./Heavy'));

// Componentes MUI
import { Box, Paper, Typography, Button, Grid } from '@mui/material';
import type { SxProps, Theme } from '@mui/material';

// TanStack Query (Suspense)
import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';

// TanStack Router
import { createFileRoute } from '@tanstack/react-router';

// Componentes del Proyecto
import { SuspenseLoader } from '~components/SuspenseLoader';

// Hooks
import { useAuth } from '@/hooks/useAuth';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';

// Tipos
import type { Post } from '~types/post';

---

Guías por Tema

🎨 Patrones de Componentes

Los componentes React modernos usan:

• React.FC<Props> para seguridad de tipos
• React.lazy() para división de código
• SuspenseLoader para estados de carga
• Patrón de constante nombrada + exportación por defecto

Conceptos Clave:

• Carga diferida de componentes pesados (DataGrid, gráficos, editores)
• Siempre envuelve componentes con carga diferida en Suspense
• Usa el componente SuspenseLoader (con animación de desvanecimiento)
• Estructura del componente: Props → Hooks → Manejadores → Render → Export

📖 Guía Completa: resources/component-patterns.md

---

📊 Obtención de Datos

PATRÓN PRINCIPAL: useSuspenseQuery

• Usa con límites de Suspense
• Estrategia de caché primero (revisar caché de la cuadrícula antes de API)
• Reemplaza las comprobaciones de isLoading
• Seguro en tipos con genéricos

Capa de Servicio API:

• Crea features/{funcionalidad}/api/{funcionalidad}Api.ts
• Usa la instancia axios apiClient
• Métodos centralizados por funcionalidad
• Formato de ruta: /form/route (NO /api/form/route)

📖 Guía Completa: resources/data-fetching.md

---

📁 Organización de Archivos

features/ vs components/:

• features/: Específico del dominio (posts, comments, auth)
• components/: Verdaderamente reutilizable (SuspenseLoader, CustomAppBar)

Subdirectorios de Funcionalidades:

features/
  mi-funcionalidad/
    api/          # Capa de servicio API
    components/   # Componentes de la funcionalidad
    hooks/        # Hooks personalizados
    helpers/      # Funciones de utilidad
    types/        # Tipos TypeScript

📖 Guía Completa: resources/file-organization.md

---

🎨 Estilizado

En línea vs Separado:

• <100 líneas: En línea const styles: Record<string, SxProps<Theme>>

• 100 líneas: Archivo .styles.ts separado

Método Principal:

• Usa la prop sx para componentes MUI
• Seguro en tipos con SxProps<Theme>
• Acceso al tema: (theme) => theme.palette.primary.main

MUI v7 Grid:

<Grid size={{ xs: 12, md: 6 }}>  // ✅ Sintaxis v7
<Grid xs={12} md={6}>             // ❌ Sintaxis antigua

📖 Guía Completa: resources/styling-guide.md

---

🛣️ Enrutamiento

TanStack Router - Basado en Carpetas:

• Directorio: routes/mi-ruta/index.tsx
• Carga diferida de componentes
• Usa createFileRoute
• Datos de migas de pan en el loader

Ejemplo:

import { createFileRoute } from '@tanstack/react-router';
import { lazy } from 'react';

const MiPagina = lazy(() => import('@/features/mi-funcionalidad/components/MiPagina'));

export const Route = createFileRoute('/mi-ruta/')({
    component: MiPagina,
    loader: () => ({ crumb: 'Mi Ruta' }),
});

📖 Guía Completa: resources/routing-guide.md

---

⏳ Estados de Carga y Error

REGLAS CRÍTICAS: Sin Retornos Tempranos

// ❌ NUNCA - Causa desplazamiento del layout
if (isLoading) {
    return <LoadingSpinner />;
}

// ✅ SIEMPRE - Layout consistente
<SuspenseLoader>
    <Content />
</SuspenseLoader>

Por qué: Previene el desplazamiento acumulativo del layout (CLS), mejor experiencia de usuario

Manejo de Errores:

• Usa useMuiSnackbar para comentarios al usuario
• NUNCA react-toastify
• Usa callbacks onError de TanStack Query

📖 Guía Completa: resources/loading-and-error-states.md

---

⚡ Rendimiento

Patrones de Optimización:

• useMemo: Cálculos costosos (filtrado, ordenamiento, mapeo)
• useCallback: Manejadores de eventos pasados a hijos
• React.memo: Componentes costosos
• Búsqueda con debounce (300-500ms)
• Prevención de fugas de memoria (limpieza en useEffect)

📖 Guía Completa: resources/performance.md

---

📘 TypeScript

Estándares:

• Modo estricto, sin tipo any
• Tipos de retorno explícitos en funciones
• Importaciones de tipos: import type { User } from '~types/user'
• Interfaces de props de componentes con JSDoc

📖 Guía Completa: resources/typescript-standards.md

---

🔧 Patrones Comunes

Temas Cubiertos:

• React Hook Form con validación Zod
• Contratos de wrappers de DataGrid
• Estándares para componentes de diálogo
• Hook useAuth para usuario actual
• Patrones de mutación con invalidación de caché

📖 Guía Completa: resources/common-patterns.md

---

📚 Ejemplos Completos

Ejemplos funcionales completos:

• Componente moderno con todos los patrones
• Estructura completa de funcionalidad
• Capa de servicio API
• Ruta con carga diferida
• Suspense + useSuspenseQuery
• Formulario con validación

📖 Guía Completa: resources/complete-examples.md

---

Guía de Navegación

Necesitas...	Lee este recurso
Crear un componente	component-patterns.md
Obtener datos	data-fetching.md
Organizar archivos/carpetas	file-organization.md
Estilizar componentes	styling-guide.md
Configurar enrutamiento	routing-guide.md
Manejar carga/errores	loading-and-error-states.md
Optimizar rendimiento	performance.md
Tipos TypeScript	typescript-standards.md
Formularios/Auth/DataGrid	common-patterns.md
Ver ejemplos completos	complete-examples.md

---

Principios Fundamentales

1. Carga Diferida de Todo lo Pesado: Rutas, DataGrid, gráficos, editores
2. Suspense para Carga: Usa SuspenseLoader, no retornos tempranos
3. useSuspenseQuery: Patrón principal de obtención de datos para código nuevo
4. Funcionalidades Organizadas: Subdirectorios api/, components/, hooks/, helpers/
5. Estilos Según Tamaño: <100 en línea, >100 separado
6. Alias de Importación: Usa @/, ~types, ~components, ~features
7. Sin Retornos Tempranos: Previene el desplazamiento del layout
8. useMuiSnackbar: Para todas las notificaciones al usuario

---

Referencia Rápida: Estructura de Archivos

src/
  features/
    mi-funcionalidad/
      api/
        miFuncionalidadApi.ts       # Servicio API
      components/
        MiFuncionalidad.tsx         # Componente principal
        SubComponente.tsx           # Componentes relacionados
      hooks/
        useMiFuncionalidad.ts       # Hooks personalizados
        useSuspenseMiFuncionalidad.ts  # Hooks con Suspense
      helpers/
        miFuncionalidadHelpers.ts   # Utilidades
      types/
        index.ts                    # Tipos TypeScript
      index.ts                      # Exportaciones públicas

  components/
    SuspenseLoader/
      SuspenseLoader.tsx            # Cargador reutilizable
    CustomAppBar/
      CustomAppBar.tsx              # Barra de aplicación reutilizable

  routes/
    mi-ruta/
      index.tsx                     # Componente de ruta
      create/
        index.tsx                   # Ruta anidada

---

Plantilla de Componente Moderno (Copia Rápida)

import React, { useState, useCallback } from 'react';
import { Box, Paper } from '@mui/material';
import { useSuspenseQuery } from '@tanstack/react-query';
import { featureApi } from '../api/featureApi';
import type { FeatureData } from '~types/feature';

interface MiComponenteProps {
    id: number;
    onAccion?: () => void;
}

export const MiComponente: React.FC<MiComponenteProps> = ({ id, onAccion }) => {
    const [state, setState] = useState<string>('');

    const { data } = useSuspenseQuery({
        queryKey: ['feature', id],
        queryFn: () => featureApi.getFeature(id),
    });

    const manejarAccion = useCallback(() => {
        setState('actualizado');
        onAccion?.();
    }, [onAccion]);

    return (
        <Box sx={{ p: 2 }}>
            <Paper sx={{ p: 3 }}>
                {/* Contenido */}
            </Paper>
        </Box>
    );
};

export default MiComponente;

Para ejemplos completos, consulta resources/complete-examples.md

---

Skills Relacionadas

• error-tracking: Seguimiento de errores con Sentry (aplica también al frontend)
• backend-dev-guidelines: Patrones de API backend que el frontend consume

---

Estado de la Skill: Estructura modular con carga progresiva para una gestión óptima del contexto