React y TypeScript en proyectos reales

Organiza por responsabilidad: pages para rutas, components para UI reutilizable, hooks para lógica, constants y data para contenido estático, lib para utilidades como structured-data y SEO. Este repositorio sigue ese patrón: data/expertise/, data/guias/, components/ExpertiseLandingLayout.tsx y types/content.ts para imágenes con atribución.

Mantén los tipos en types/ o co-localizados con componentes. Evita any; usa discriminated unions y exhaustive switch para estados de UI. Los datos de contenido (proyectos, FAQ, guías) funcionan bien como módulos TypeScript exportados — facilitan lint, autocompletado y refactors seguros.

Separa layout de página y presentación: ExpertiseLandingLayout consume datos de data/expertise/*.ts; las páginas DesarrolloWeb.tsx son wrappers de una línea. Eso escala cuando añades secciones narrativas sin inflar componentes de ruta.

Centraliza tokens de diseño y variables CSS — este proyecto usa Tailwind CSS 4 con design system documentado. Consistencia visual entre home, expertise y guías refuerza marca personal.

En Neacsu Horizont Ventures el ciclo completo incluye levantamiento de requisitos y arquitectura antes del primer componente React. Esa disciplina evita deuda en rutas, estado global innecesario y props drilling evitable.

Define interfaces de props explícitas. Usa const para arrays de configuración y satisfies cuando necesites inferencia estrecha. Los datos de contenido (proyectos, FAQ, guías) funcionan bien como módulos TypeScript exportados con interfaces NarrativeSection y ContentImage.

Para rutas dinámicas (/proyectos/:slug, /guias/:slug), valida el slug contra una lista const (GUIDE_SLUGS, PROJECT_SLUGS) y redirige con Navigate si no existe. Eso previene URLs basura y simplifica SEO.

Tipa respuestas de APIs externas — GitHub repos, LinkedIn sync — con interfaces dedicadas en types/. Valida en runtime solo cuando la fuente es inestable; confía en tipos cuando generas datos con scripts propios.

Certificación Fundamentos UX/UI (UCP, 2024) influye en props de accesibilidad: aria-labels, contraste, focus visible. TypeScript no reemplaza pruebas de accesibilidad pero sí evita props olvidadas en componentes Button reutilizables.

Usa never en default de switch sobre uniones discriminadas — regla del proyecto — para que nuevos variants fallen en compile-time hasta que los manejes.

react-helmet-async inyecta meta tags en runtime, pero crawlers necesitan HTML estático: prerender con Puppeteer en build, JSON-LD en cada página y llms.txt para agentes de IA. SeoHelmet centraliza title, description, canonical, Open Graph y structured data.

Centraliza SITE_URL, títulos y descriptions en constants/seo-pages.ts para mantener consistencia entre componentes, sitemap y llms.txt. Las páginas de expertise usan buildExpertiseStructuredData; las guías, buildArticleStructuredData con datePublished y dateModified.

Clases semánticas direct-answer y faq-answer marcan párrafos que motores de respuesta pueden citar. Combínalas con contenido narrativo largo basado en experiencia real — LinkedIn, GitHub, certificaciones — no texto placeholder.

Optimiza imágenes con componentes lazy-loaded (OptimizedImage) y figuras con atribución (ContentImageFigure) cuando uses fotos de LinkedIn o capturas de repos. Crédito visible evita problemas de derechos y aumenta confianza.

Despliega en Vercel con preview por PR; pipelines CI/CD en proyectos profesionales (Prosavis, Neacsu) extienden la misma mentalidad: lint, build y verificación antes de merge.