Frontend Senior
Patrones de desarrollo frontend, optimización del rendimiento y herramientas de automatización para aplicaciones React/Next.js.
Tabla de Contenidos
- Scaffolding de Proyectos
- Generación de Componentes
- Análisis de Paquetes
- Patrones de React
- Optimización de Next.js
- Accesibilidad y Pruebas
Scaffolding de Proyectos
Genera un nuevo proyecto Next.js o React con TypeScript, Tailwind CSS y configuraciones de mejores prácticas.
Flujo de Trabajo: Crear Nuevo Proyecto Frontend
-
Ejecuta el scaffolder con el nombre de tu proyecto y la plantilla:
python scripts/frontend_scaffolder.py my-app --template nextjs -
Agrega características opcionales (auth, api, forms, testing, storybook):
python scripts/frontend_scaffolder.py dashboard --template nextjs --features auth,api -
Navega al proyecto e instala las dependencias:
cd my-app && npm install -
Inicia el servidor de desarrollo:
npm run dev
Opciones del Scaffolder
| Opción | Descripción |
|---|---|
--template nextjs | Next.js 14+ con App Router y Server Components |
--template react | React + Vite con TypeScript |
--features auth | Agrega autenticación con NextAuth.js |
--features api | Agrega React Query + cliente API |
--features forms | Agrega React Hook Form + validación Zod |
--features testing | Agrega Vitest + Testing Library |
--dry-run | Vista previa de los archivos sin crearlos |
Estructura Generada (Next.js)
my-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), constants
├── types/ # Interfaces TypeScript
├── tailwind.config.ts
├── next.config.js
└── package.json
Generación de Componentes
Genera componentes React con TypeScript, pruebas e historias 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 e historia:
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 React personalizado |
--with-test | Incluye archivo de prueba |
--with-story | Incluye historia de Storybook |
--flat | Crea en el directorio de salida sin subdirectorio |
--dry-run | Vista previa 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 Paquetes
Analiza package.json y la estructura del proyecto para oportunidades de optimización del paquete.
Flujo de Trabajo: Optimizar el Tamaño del Paquete
-
Ejecuta el analizador en tu proyecto:
python scripts/bundle_analyzer.py /path/to/project -
Revisa la puntuación de salud y los problemas:
Puntuación de Salud del Paquete: 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 Paquete
| Puntuación | Calificación | Acción |
|---|---|---|
| 90-100 | A | El paquete está bien optimizado |
| 80-89 | B | Optimizaciones menores disponibles |
| 70-79 | C | Reemplazar dependencias pesadas |
| 60-69 | D | Múltiples problemas requieren atención |
| 0-59 | F | Problemas críticos de tamaño del paquete |
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 de 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 debouncedSearch = useDebounce(searchTerm, 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/users"
render={({ data, loading }) =>
loading ? <Spinner /> : <UserList users={data} />
}
/>
Optimización de Next.js
Referencia: references/nextjs_optimization_guide.md
Componentes Servidor vs. Cliente
Usa Server Components por defecto. Agrega 'use client' solo cuando necesites:
- Manejadores de eventos (onClick, onChange)
- Estado (useState, useReducer)
- Efectos (useEffect)
- APIs del navegador
// Server Component (por defecto) - sin 'use client'
async function ProductPage({ params }) {
const product = await getProduct(params.id); // Obtención del lado del servidor
return (
<div>
<h1>{product.name}</h1>
<AddToCartButton productId={product.id} /> {/* Componente cliente */}
</div>
);
}
// Client Component
'use client';
function AddToCartButton({ productId }) {
const [adding, setAdding] = useState(false);
return <button onClick={() => addToCart(productId)}>Agregar</button>;
}
Optimización de Imágenes
import Image from 'next/image';
// Above the fold - cargar inmediatamente
<Image
src="/hero.jpg"
alt="Hero"
width={1200}
height={600}
priority
/>
// Imagen responsiva con fill
<div className="relative aspect-video">
<Image
src="/product.jpg"
alt="Producto"
fill
sizes="(max-width: 768px) 100vw, 50vw"
className="object-cover"
/>
</div>
Patrones de Obtención de Datos
// Obtención en paralelo
async function Dashboard() {
const [user, stats] = await Promise.all([
getUser(),
getStats()
]);
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="#main-content" 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 desencadena una 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: [{ protocol: 'https', hostname: 'cdn.example.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 de 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 de React:
references/react_patterns.md - Optimización de Next.js:
references/nextjs_optimization_guide.md - Mejores Prácticas:
references/frontend_best_practices.md - Biblioteca forcing-question (grill de Matt Pocock):
references/forcing_questions.md - Mapa de composición (a qué especialista bifurcar):
references/composition_map.md
Suposiciones y Criterios de Éxito Verificables (disciplina Karpathy)
Antes de que esta habilidad genere un componente, recomiende un framework o audite un paquete, las siguientes cuatro suposiciones DEBEN ser presentadas.
- Dispositivo primario del usuario + red — móvil-4G, escritorio-fibra, Android de gama baja o red corporativa. Impulsa cada decisión de rendimiento.
- Objetivo LCP en milisegundos — un solo número, no "rápido". Impulsa el presupuesto del paquete y la elección de renderizado.
- Dependiente de SEO vs. protegido por autenticación — impulsa el renderizado (SSR/SSG/RSC vs. SPA).
- Objetivo WCAG + propietario 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 primario
- Un presupuesto de paquete JS por ruta en KB-gzip
- Un piso de Lighthouse a11y + piso de rendimiento
Si no se indica alguno de estos tres, la recomendación está incompleta: regresa a Q2 de la biblioteca forcing-question.
La herramienta scripts/frontend_decision_engine.py codifica estas verificaciones: se niega a recomendar un perfil sin las cuatro entradas de suposición 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 elegir | Objetivo LCP (móvil-4G p75) | Presupuesto de paquete |
|---|---|---|---|
next-app-router | SaaS orientado al cliente, SEO + dinámico, RSC-first | 2000ms | 150 KB-gzip / ruta |
remix-or-sveltekit | Móvil-4G primario, low-JS-first, mejora progresiva | 1500ms | 80 KB-gzip / ruta |
vite-spa | App protegida por auth, escritorio/corporativo primario | 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 de mejor ajuste, el trade-off del segundo mejor (si está dentro del 15%), las opciones de stack, los anti-patrones a evitar en ese perfil y las puertas de CI requeridas.
Para agregar un perfil personalizado (por ejemplo, los valores predeterminados de herramientas internas de tu organización): copia profiles/vite-spa.json a profiles/<tu-organizacion>.json y ajusta constraints + success_thresholds.
Mapa de Composición
Esta habilidad NO reimplementa el alcance que pertenece a los especialistas de nivel POWERFUL. Se bifurca hacia ellos. Consulta references/composition_map.md para la tabla de enrutamiento completa. Bifurcaciones clave:
| Asunto | Bifurcar hacia |
|---|---|
| Auditoría WCAG, contraste, lector de pantalla | engineering-team/skills/a11y-audit/ |
| Perfilado de paquetes + rendimiento en tiempo de ejecución | engineering/skills/performance-profiler/ |
| Página de aterrizaje cinematográfica / narración con scroll | engineering-team/skills/epic-design/ |
| Apple HIG (iOS / macOS / visionOS) | product-team/skills/apple-hig-expert/ |
| Revisión pre-commit Karpathy | engineering/karpathy-coder/ |
| Grill de arquitectura prevuelo | 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
…
[truncado para traducción]