Frontend Senior
Patrones de desarrollo frontend, optimización de rendimiento y herramientas de automatización para aplicaciones React/Next.js.
Tabla de Contenidos
- Inicio de Proyectos
- Generación de Componentes
- Análisis de Bundle
- Patrones React
- Optimización Next.js
- Accesibilidad y Pruebas
Inicio de Proyectos
Genera un nuevo proyecto Next.js o React con TypeScript, Tailwind CSS y configuraciones de buenas prácticas.
Flujo de Trabajo: Crear Nuevo Proyecto Frontend
-
Ejecuta el generador con el nombre de tu proyecto y la plantilla:
python scripts/frontend_scaffolder.py mi-app --template nextjs -
Añade características opcionales (auth, api, formularios, testing, storybook):
python scripts/frontend_scaffolder.py dashboard --template nextjs --features auth,api -
Navega al proyecto e instala las dependencias:
cd mi-app && npm install -
Inicia el servidor de desarrollo:
npm run dev
Opciones del Generador
| Opción | Descripción |
|---|---|
--template nextjs | Next.js 14+ con App Router y Componentes Servidor |
--template react | React + Vite con TypeScript |
--features auth | Añade autenticación NextAuth.js |
--features api | Añade React Query + cliente API |
--features forms | Añade React Hook Form + validación Zod |
--features testing | Añade Vitest + Testing Library |
--dry-run | Previsualiza archivos sin crearlos |
Estructura Generada (Next.js)
mi-app/
├── app/
│ ├── layout.tsx # Layout raíz con fuentes
│ ├── page.tsx # Página de inicio
│ ├── globals.css # Tailwind + variables CSS
│ └── api/health/route.ts
├── components/
│ ├── ui/ # Button, Input, Card
│ └── layout/ # Header, Footer, Sidebar
├── hooks/ # useDebounce, useLocalStorage
├── lib/ # utils (cn), constantes
├── types/ # Interfaces TypeScript
├── tailwind.config.ts
├── next.config.js
└── package.json
Generación de Componentes
Genera componentes React con TypeScript, pruebas y stories de Storybook.
Flujo de Trabajo: Crear un Nuevo Componente
-
Genera un componente cliente:
python scripts/component_generator.py Button --dir src/components/ui -
Genera un componente servidor:
python scripts/component_generator.py ProductCard --type server -
Genera con archivos de prueba y story:
python scripts/component_generator.py UserProfile --with-test --with-story -
Genera un hook personalizado:
python scripts/component_generator.py FormValidation --type hook
Opciones del Generador
| Opción | Descripción |
|---|---|
--type client | Componente cliente con 'use client' (por defecto) |
--type server | Componente servidor asíncrono |
--type hook | Hook personalizado de React |
--with-test | Incluye archivo de prueba |
--with-story | Incluye story de Storybook |
--flat | Crea en el directorio de salida sin subdirectorio |
--dry-run | Previsualiza sin crear archivos |
Ejemplo de Componente Generado
'use client';
import { useState } from 'react';
import { cn } from '@/lib/utils';
interface ButtonProps {
className?: string;
children?: React.ReactNode;
}
export function Button({ className, children }: ButtonProps) {
return (
<div className={cn('', className)}>
{children}
</div>
);
}
Análisis de Bundle
Analiza el package.json y la estructura del proyecto para identificar oportunidades de optimización del bundle.
Flujo de Trabajo: Optimizar Tamaño del Bundle
-
Ejecuta el analizador en tu proyecto:
python scripts/bundle_analyzer.py /ruta/al/proyecto -
Revisa la puntuación de salud y los problemas:
Puntuación de Salud del Bundle: 75/100 (C) DEPENDENCIAS PESADAS: moment (290KB) Alternativa: date-fns (12KB) o dayjs (2KB) lodash (71KB) Alternativa: lodash-es con tree-shaking -
Aplica las correcciones recomendadas reemplazando las dependencias pesadas.
-
Vuelve a ejecutar en modo verbose para verificar los patrones de importación:
python scripts/bundle_analyzer.py . --verbose
Interpretación de la Puntuación del Bundle
| Puntuación | Calificación | Acción |
|---|---|---|
| 90-100 | A | Bundle bien optimizado |
| 80-89 | B | Optimizaciones menores disponibles |
| 70-79 | C | Reemplazar dependencias pesadas |
| 60-69 | D | Múltiples problemas que requieren atención |
| 0-59 | F | Problemas críticos de tamaño del bundle |
Dependencias Pesadas Detectadas
El analizador identifica estos paquetes pesados comunes:
| Paquete | Tamaño | Alternativa |
|---|---|---|
| moment | 290KB | date-fns (12KB) o dayjs (2KB) |
| lodash | 71KB | lodash-es con tree-shaking |
| axios | 14KB | fetch nativo o ky (3KB) |
| jquery | 87KB | APIs DOM nativas |
| @mui/material | Grande | shadcn/ui o Radix UI |
Patrones React
Referencia: references/react_patterns.md
Componentes Compuestos
Comparte estado entre componentes relacionados:
const Tabs = ({ children }) => {
const [active, setActive] = useState(0);
return (
<TabsContext.Provider value={{ active, setActive }}>
{children}
</TabsContext.Provider>
);
};
Tabs.List = TabList;
Tabs.Panel = TabPanel;
// Uso
<Tabs>
<Tabs.List>
<Tabs.Tab>Uno</Tabs.Tab>
<Tabs.Tab>Dos</Tabs.Tab>
</Tabs.List>
<Tabs.Panel>Contenido 1</Tabs.Panel>
<Tabs.Panel>Contenido 2</Tabs.Panel>
</Tabs>
Hooks Personalizados
Extrae lógica reutilizable:
function useDebounce<T>(value: T, delay = 500): T {
const [debouncedValue, setDebouncedValue] = useState(value);
useEffect(() => {
const timer = setTimeout(() => setDebouncedValue(value), delay);
return () => clearTimeout(timer);
}, [value, delay]);
return debouncedValue;
}
// Uso
const busquedaDebounced = useDebounce(terminoBusqueda, 300);
Render Props
Comparte lógica de renderizado:
function DataFetcher({ url, render }) {
const [data, setData] = useState(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
fetch(url).then(r => r.json()).then(setData).finally(() => setLoading(false));
}, [url]);
return render({ data, loading });
}
// Uso
<DataFetcher
url="/api/usuarios"
render={({ data, loading }) =>
loading ? <Spinner /> : <UserList users={data} />
}
/>
Optimización Next.js
Referencia: references/nextjs_optimization_guide.md
Componentes Servidor vs Cliente
Usa Componentes Servidor por defecto. Añade 'use client' solo cuando necesites:
- Manejadores de eventos (onClick, onChange)
- Estado (useState, useReducer)
- Efectos (useEffect)
- APIs del navegador
// Componente Servidor (por defecto) - sin 'use client'
async function ProductPage({ params }) {
const product = await getProduct(params.id); // Fetch en el servidor
return (
<div>
<h1>{product.name}</h1>
<AddToCartButton productId={product.id} /> {/* Componente Cliente */}
</div>
);
}
// Componente Cliente
'use client';
function AddToCartButton({ productId }) {
const [adding, setAdding] = useState(false);
return <button onClick={() => addToCart(productId)}>Añadir</button>;
}
Optimización de Imágenes
import Image from 'next/image';
// Above the fold - carga inmediata
<Image
src="/hero.jpg"
alt="Hero"
width={1200}
height={600}
priority
/>
// Imagen responsive con fill
<div className="relative aspect-video">
<Image
src="/producto.jpg"
alt="Producto"
fill
sizes="(max-width: 768px) 100vw, 50vw"
className="object-cover"
/>
</div>
Patrones de Obtención de Datos
// Fetch en paralelo
async function Dashboard() {
const [usuario, estadisticas] = await Promise.all([
getUsuario(),
getEstadisticas()
]);
return <div>...</div>;
}
// Streaming con Suspense
async function ProductPage({ params }) {
return (
<div>
<ProductDetails id={params.id} />
<Suspense fallback={<ReviewsSkeleton />}>
<Reviews productId={params.id} />
</Suspense>
</div>
);
}
Accesibilidad y Pruebas
Referencia: references/frontend_best_practices.md
Lista de Verificación de Accesibilidad
- HTML Semántico: Usa elementos apropiados (
<button>,<nav>,<main>) - Navegación por Teclado: Todos los elementos interactivos deben ser enfocables
- Etiquetas ARIA: Proporciona etiquetas para iconos y widgets complejos
- Contraste de Color: Mínimo 4.5:1 para texto normal
- Indicadores de Enfoque: Estados de enfoque visibles
// Botón accesible
<button
type="button"
aria-label="Cerrar diálogo"
onClick={onClose}
className="focus-visible:ring-2 focus-visible:ring-blue-500"
>
<XIcon aria-hidden="true" />
</button>
// Enlace de salto para usuarios de teclado
<a href="#contenido-principal" className="sr-only focus:not-sr-only">
Saltar al contenido principal
</a>
Estrategia de Pruebas
// Prueba de componente con React Testing Library
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
test('el botón ejecuta la acción al hacer clic', async () => {
const onClick = vi.fn();
render(<Button onClick={onClick}>Haz clic</Button>);
await userEvent.click(screen.getByRole('button'));
expect(onClick).toHaveBeenCalledTimes(1);
});
// Prueba de accesibilidad
test('el diálogo es accesible', async () => {
render(<Dialog open={true} title="Confirmar" />);
expect(screen.getByRole('dialog')).toBeInTheDocument();
expect(screen.getByRole('dialog')).toHaveAttribute('aria-labelledby');
});
Referencia Rápida
Configuración Común de Next.js
// next.config.js
const nextConfig = {
images: {
remotePatterns: [{ hostname: "ejemplocdn.com" }],
formats: ['image/avif', 'image/webp'],
},
experimental: {
optimizePackageImports: ['lucide-react', '@heroicons/react'],
},
};
Utilidades de Tailwind CSS
// Clases condicionales con cn()
import { cn } from '@/lib/utils';
<button className={cn(
'px-4 py-2 rounded',
variant === 'primary' && 'bg-blue-500 text-white',
disabled && 'opacity-50 cursor-not-allowed'
)} />
Patrones TypeScript
// Props con children
interface CardProps {
className?: string;
children: React.ReactNode;
}
// Componente genérico
interface ListProps<T> {
items: T[];
renderItem: (item: T) => React.ReactNode;
}
function List<T>({ items, renderItem }: ListProps<T>) {
return <ul>{items.map(renderItem)}</ul>;
}
Recursos
- Patrones React:
references/react_patterns.md - Optimización Next.js:
references/nextjs_optimization_guide.md - Mejores Prácticas:
references/frontend_best_practices.md - Librería de preguntas forzadas (Matt Pocock grill):
references/forcing_questions.md - Mapa de composición (a qué especialista bifurcar):
references/composition_map.md
Supuestos y Criterios de Éxito Verificables (Disciplina Karpathy)
Antes de que esta habilidad genere un componente, recomiende un framework o audite un bundle, DEBEN presentarse los siguientes cuatro supuestos.
- Dispositivo principal del usuario + red — móvil-4G, escritorio-fibra, Android-gama-baja o red-corporativa. Impulsa cada decisión de rendimiento.
- Objetivo de LCP en milisegundos — un solo número, no "rápido". Impulsa el presupuesto del bundle y la elección de renderizado.
- Dependiente de SEO vs. protegido por autenticación — impulsa el renderizado (SSR/SSG/RSC vs. SPA).
- Objetivo WCAG + responsable de a11y nombrado — AA, AAA, o mejor esfuerzo. Impulsa la inversión en a11y y las puertas de CI.
Criterios de éxito verificables (Karpathy #4) — cada recomendación debe incluir:
- Objetivos de Core Web Vitals (LCP, INP, CLS) en p75 en el dispositivo principal
- Un presupuesto de bundle JS por ruta en KB-gzip
- Un piso de Lighthouse para a11y + un piso de rendimiento
Si alguno de estos tres no se declara, la recomendación está incompleta: vuelve a Q2 de la librería de preguntas forzadas.
La herramienta scripts/frontend_decision_engine.py codifica estas verificaciones: se niega a recomendar un perfil sin las cuatro entradas de supuestos e imprime los umbrales verificables para el perfil coincidente.
Perfiles de Personalización
Cuatro perfiles integrados en profiles/ calibran cada recomendación:
| Perfil | Cuándo elegirlo | Objetivo de LCP (móvil-4G p75) | Presupuesto de bundle |
|---|---|---|---|
next-app-router | SaaS orientado al cliente, SEO + dinámico, RSC-first | 2000ms | 150 KB-gzip / ruta |
remix-or-sveltekit | Móvil-4G principal, low-JS-first, mejora progresiva | 1500ms | 80 KB-gzip / ruta |
vite-spa | App protegida por autenticación, escritorio/corporativo principal | 2500ms | 200 KB init + 80 KB / ruta |
astro-or-static | Marketing / docs / blog, escritura casi nula, SEO crítico | 1200ms | 30 KB JS / página |
Elige un perfil mediante:
python scripts/frontend_decision_engine.py \
--primary-device mobile-4g --lcp-target-ms 2000 \
--seo-dependent true --auth-walled false --team-size 5
La herramienta devuelve el perfil más adecuado, la alternativa secundaria (si está dentro del 15%), las opciones de stack, los anti-patrones a evitar en ese perfil y las puertas de CI requeridas.
Para añadir un perfil personalizado (por ejemplo, los valores predeterminados de tu organización para herramientas internas): copia profiles/vite-spa.json a profiles/<tu-organizacion>.json y ajusta constraints + success_thresholds.
Mapa de Composición
Esta habilidad NO reimplementa el ámbito que pertenece a los especialistas de nivel POWERFUL. Bifurca hacia ellos. Consulta references/composition_map.md para la tabla de enrutamiento completa. Bifurcaciones clave:
| Ámbito | Bifurcar hacia |
|---|---|
| Auditoría WCAG, contraste, lector de pantalla | engineering-team/skills/a11y-audit/ |
| Perfilado de bundle + rendimiento en tiempo de ejecución | engineering/skills/performance-profiler/ |
| Landing cinematográfico / narrativa de desplazamiento | engineering-team/skills/epic-design/ |
| Apple HIG (iOS / macOS / visionOS) | product-team/skills/apple-hig-expert/ |
| Revisión Karpathy previa al commit | engineering/karpathy-coder/ |
| Análisis previo a la arquitectura | engineering/grill-me/ |
El agente cs-frontend-engineer orquesta estas bifurcaciones mediante context: fork. Invócalo desde otro agente con Agent({subagent_type: "cs-frontend-engineer", prompt: "..."}) o mediante /cs:frontend-rev
Herramientas
frontend_scaffolder.py
Genera nuevas aplicaciones frontend con configuraciones predefinidas.
Uso básico:
python scripts/frontend_scaffolder.py nombre-del-proyecto --template nextjs
Todos los argumentos:
flag tipo descripción
--template str Plantilla del proyecto ("nextjs", "react", "astro")
--features str Lista separada por comas de características opcionales ("auth,api,forms,testing,storybook")
--dry-run flag Previsualizar archivos sin escribirlos en el disco
component_generator.py
Genera componentes individuales de React con pruebas y stories.
Uso básico:
python scripts/component_generator.py NombreDelComponente --dir src/components
Todos los argumentos:
flag tipo descripción
name str Nombre del componente a generar
--dir str Directorio de salida (por defecto: src/components)
--type str Tipo de componente ("client", "server", "hook"; por defecto: client)
--with-test flag Incluye archivo de prueba
--with-story flag Incluye story de Storybook
--flat flag Crea en el directorio de salida sin subdirectorio anidado
--dry-run flag Previsualizar archivos sin escribirlos en el disco
bundle_analyzer.py
Analiza el bundle de la aplicación en busca de dependencias pesadas, importaciones ineficientes y oportunidades de optimización.
Uso básico:
python scripts/bundle_analyzer.py /ruta/al/proyecto
Todos los argumentos:
flag tipo descripción
project-path str Ruta al proyecto a analizar
--verbose flag Muestra patrones de importación detallados
--json flag Salida en formato JSON para consumo por otras herramientas
--fail-below int Puntuación mínima de salud del bundle (por defecto: 70); falla si está por debajo
frontend_decision_engine.py
Hace coincidir las características del proyecto con el perfil de pila técnica y los umbrales de éxito más adecuados.
Uso básico:
python scripts/frontend_decision_engine.py --primary-device mobile-4g --lcp-target-ms 2000 --seo-dependent true --auth-walled false --team-size 5
Todos los argumentos:
flag tipo descripción
--primary-device str Dispositivo principal del usuario ("mobile-4g", "desktop-fiber", "low-end-android", "corporate-network")
--lcp-target-ms int Objetivo de Largest Contentful Paint en milisegundos (por ejemplo, 2000)
--seo-dependent str "true" si el proyecto depende del SEO, "false" en caso contrario
--auth-walled str "true" si el proyecto requiere autenticación, "false" en caso contrario
--team-size int Número de desarrolladores que trabajarán en el proyecto
--profile-custom str Ruta a un archivo de perfil personalizado JSON (opcional)
--dry-run flag Muestra el perfil coincidente y los umbrales sin generar ni modificar nada