Boilerplate React + TypeScript + Vite

Este proyecto es un boilerplate (plantilla base) muy simple de React diseñado para servir como punto de partida en el desarrollo de aplicaciones web modernas. Incluye una configuración mínima pero funcional con las herramientas esenciales para comenzar a trabajar de inmediato. El boilerplate es completamente responsive y se adapta automáticamente a diferentes tamaños de pantalla y dispositivos, desde móviles hasta pantallas de escritorio.

¿Qué es un boilerplate?

Un boilerplate es una plantilla de proyecto preconfigurada que incluye la estructura básica, dependencias y configuración necesarias para iniciar un nuevo proyecto sin tener que configurar todo desde cero. Este boilerplate te permite comenzar a desarrollar componentes y vistas de React inmediatamente.

Tecnologías utilizadas

Este proyecto utiliza las siguientes tecnologías principales:

• React 19.2.0: Biblioteca de JavaScript para construir interfaces de usuario mediante componentes reutilizables. Permite crear aplicaciones interactivas de forma eficiente.

• TypeScript: Extensión de JavaScript que añade tipado estático. Ayuda a detectar errores durante el desarrollo y mejora la mantenibilidad del código mediante tipos explícitos.

• Vite: Herramienta de build y servidor de desarrollo extremadamente rápida. Proporciona Hot Module Replacement (HMR), lo que significa que los cambios en el código se reflejan instantáneamente en el navegador sin recargar la página completa.

• React Router DOM 7.12.0: Biblioteca para manejar el enrutamiento en aplicaciones React de una sola página (SPA). Permite navegar entre diferentes vistas sin recargar la página.

• ESLint: Herramienta de análisis estático que identifica problemas en el código JavaScript/TypeScript. Ayuda a mantener un código consistente y libre de errores comunes.

Estructura del proyecto

El proyecto está organizado de la siguiente manera:

src/
├── components/          # Componentes reutilizables
│   ├── Button/         # Componente de botón
│   ├── Card/           # Componente de tarjeta
│   ├── Layout/         # Componente Layout común
│   └── Paragraph/      # Componente de párrafo
├── views/              # Vistas/páginas de la aplicación
│   └── HomeView/       # Vista principal de ejemplo
├── App.tsx             # Componente raíz con configuración de rutas
├── main.tsx            # Punto de entrada de la aplicación
├── App.css             # Estilos de la aplicación
└── index.css           # Estilos globales y variables CSS

Descripción de directorios principales

• src/components/: Contiene componentes reutilizables que pueden ser utilizados en múltiples partes de la aplicación. Cada componente tiene su propia carpeta con el archivo TypeScript y su archivo CSS correspondiente.

• src/views/: Contiene las vistas o páginas principales de la aplicación. Cada vista representa una ruta diferente en la aplicación. Todas las vistas están automáticamente envueltas por el componente Layout.

• src/App.tsx: Es el componente raíz que configura el enrutamiento de la aplicación usando React Router. Define qué componente se muestra para cada ruta y envuelve todas las rutas con el componente Layout.

• src/main.tsx: Es el punto de entrada de la aplicación. Aquí se inicializa React y se renderiza el componente App en el DOM.

• src/index.css: Contiene los estilos globales y todas las variables CSS del sistema de diseño, incluyendo la paleta de azules, espaciado, tipografía, bordes y sombras.

Componentes incluidos

El boilerplate incluye varios componentes que demuestran patrones básicos de desarrollo:

Layout

Componente que proporciona una estructura común para todas las páginas de la aplicación. Incluye un header con navegación, un área de contenido principal y un footer. Todas las vistas están automáticamente envueltas por este componente, garantizando una apariencia consistente en toda la aplicación.

Características:

• Header con fondo azul primario y navegación
• Área de contenido principal con contenedor centrado
• Footer con fondo azul oscuro
• Diseño completamente responsive: Se adapta automáticamente a móviles, tablets y escritorio
• Sin scroll horizontal: Control de overflow para evitar desbordes en cualquier dispositivo
• Navegación adaptativa: El menú se reorganiza según el tamaño de pantalla

El Layout se aplica automáticamente a todas las rutas definidas en App.tsx, por lo que no necesitas importarlo manualmente en tus vistas.

Button

Componente de botón reutilizable que puede realizar dos acciones principales:

• Navegación a URLs: Puede redirigir a una URL interna o externa
• Ejecución de funciones: Puede ejecutar una función personalizada cuando se hace clic

Props disponibles:

• text (requerido): Texto que se muestra en el botón
• url (opcional): URL a la que navegar cuando se hace clic
• external (opcional): Si es true, abre la URL en una nueva pestaña
• onClick (opcional): Función personalizada que se ejecuta al hacer clic

Ejemplo de uso:

<Button text="Abrir página de Google" url="https://www.google.es" external={true} />

Card

Componente de tarjeta reutilizable que proporciona un contenedor estilizado para agrupar contenido relacionado. Es ideal para mostrar información estructurada, formularios, o cualquier contenido que necesite ser destacado visualmente.

Características:

• Diseño completamente responsive: Se adapta automáticamente a diferentes tamaños de pantalla
• Estilos consistentes: Utiliza las variables del sistema de diseño (colores, espaciado, bordes, sombras)
• Fondo con borde azul primario y sombra para destacar el contenido
• Manejo de palabras largas: Incluye overflow-wrap y word-wrap para evitar desbordes

Props disponibles:

• children (requerido): Contenido que se mostrará dentro de la tarjeta
• className (opcional): Clases CSS adicionales para personalización

Ejemplo de uso:

<Card>
  <Paragraph text="Contenido de la tarjeta" />
  <Button text="Acción" url="/ruta" />
</Card>

Paragraph

Componente simple para mostrar texto con formato. Útil para mantener consistencia en el estilo de los párrafos a lo largo de la aplicación.

Props disponibles:

• text (requerido): Texto que se muestra en el párrafo

Ejemplo de uso:

<Paragraph text="src/views/HomeView/HomeView.tsx" />

Funcionalidad actual

El proyecto incluye la siguiente funcionalidad básica:

1. Configuración de React Router: El enrutamiento está configurado en App.tsx usando BrowserRouter, Routes y Route. Actualmente hay una ruta configurada para la página principal (/).

2. Layout común: Todas las páginas comparten un Layout consistente con header, área de contenido y footer, garantizando una apariencia uniforme en toda la aplicación.

3. Sistema de diseño con paleta de azules: El proyecto utiliza un sistema de diseño basado en tonalidades de azul, con variables CSS centralizadas para colores, espaciado, tipografía, bordes y sombras. Soporta modo claro y oscuro automáticamente.

4. Diseño responsive completo: El boilerplate está optimizado para funcionar perfectamente en todos los dispositivos. Incluye media queries para móviles (hasta 640px), tablets pequeñas (641px-768px), tablets (769px-1024px) y escritorio (1025px+). Todos los componentes, incluyendo el Layout, las cards y la navegación, se adaptan automáticamente al tamaño de pantalla.

5. Vista de ejemplo (HomeView): Una vista de demostración que muestra cómo utilizar los componentes Button, Card y Paragraph. Esta vista sirve como referencia para crear nuevas vistas y demuestra el diseño responsive en acción.

6. Hot Module Replacement (HMR): Gracias a Vite, cualquier cambio que realices en el código se reflejará automáticamente en el navegador sin necesidad de recargar manualmente la página.

7. TypeScript configurado: El proyecto está completamente tipado, lo que proporciona autocompletado y detección de errores en el editor.

Scripts disponibles

El proyecto incluye los siguientes scripts npm para diferentes tareas:

• npm run dev: Inicia el servidor de desarrollo de Vite. Abre la aplicación en http://localhost:5173 (o el puerto que Vite asigne automáticamente). Este comando debe ejecutarse durante el desarrollo.

• npm run build: Compila el proyecto para producción. Ejecuta TypeScript para verificar tipos y luego construye una versión optimizada del proyecto en la carpeta dist/. Esta versión está lista para ser desplegada.

• npm run lint: Ejecuta ESLint para analizar el código y detectar posibles problemas, errores o inconsistencias en el estilo del código.

• npm run preview: Previsualiza la build de producción localmente. Útil para verificar cómo se verá la aplicación una vez compilada antes de desplegarla.

Cómo empezar

Prerrequisitos

Asegúrate de tener instalado Node.js (versión 18 o superior) y npm en tu sistema.

Instalación

1. Instala las dependencias del proyecto ejecutando:

npm install

Este comando leerá el archivo package.json e instalará todas las dependencias necesarias en la carpeta node_modules/.

Ejecutar el servidor de desarrollo

Una vez instaladas las dependencias, ejecuta:

npm run dev

Esto iniciará el servidor de desarrollo y podrás ver la aplicación en tu navegador. La URL se mostrará en la terminal (generalmente http://localhost:5173).

Estructura para agregar nuevas funcionalidades

Agregar una nueva vista

1. Crea una nueva carpeta en src/views/ con el nombre de tu vista (por ejemplo, AboutView)
2. Crea los archivos AboutView.tsx y AboutView.css dentro de esa carpeta
3. Define tu componente en el archivo .tsx. La vista se renderizará automáticamente dentro del Layout común
4. Agrega la ruta en src/App.tsx:

import AboutView from './views/AboutView/AboutView'

// Dentro del componente App, dentro del Layout, agrega:
<Route path="/about" element={<AboutView />} />

Nota: Todas las vistas se renderizan automáticamente dentro del Layout, por lo que no necesitas preocuparte por la estructura de header y footer. Solo enfócate en el contenido principal de tu vista.

Agregar un nuevo componente

1. Crea una nueva carpeta en src/components/ con el nombre de tu componente
2. Crea los archivos ComponentName.tsx y ComponentName.css
3. Define la interfaz de props usando TypeScript
4. Implementa el componente y expórtalo como default
5. Importa y usa el componente donde lo necesites

Sistema de diseño

El proyecto utiliza un sistema de diseño basado en tonalidades de azul con variables CSS centralizadas. Todas las variables están definidas en src/index.css y pueden ser utilizadas en cualquier componente. El sistema está completamente optimizado para ser responsive y funcionar en todos los dispositivos.

Paleta de azules

Modo oscuro:

• Azul primario: #3b82f6 (--blue-primary)
• Azul hover: #2563eb (--blue-hover)
• Azul claro: #60a5fa (--blue-light)
• Azul oscuro: #1e40af (--blue-dark)
• Azul muy oscuro: #1e3a8a (--blue-darker)

Modo claro:

• Azul primario: #2563eb (--blue-primary)
• Azul hover: #1d4ed8 (--blue-hover)
• Azul claro: #3b82f6 (--blue-light)
• Azul suave: #dbeafe (--blue-soft)

Variables CSS disponibles

El proyecto incluye variables para:

• Colores: Paleta de azules, fondos y textos
• Espaciado: --spacing-xs, --spacing-sm, --spacing-md, --spacing-lg, --spacing-xl, --spacing-2xl
• Tipografía: Tamaños de fuente y pesos
• Bordes: Radios y anchos
• Sombras: --shadow-sm, --shadow-md, --shadow-lg
• Transiciones: --transition-fast, --transition-base, --transition-slow

Ejemplo de uso:

.mi-componente {
  background-color: var(--blue-primary);
  padding: var(--spacing-md);
  border-radius: var(--border-radius);
  box-shadow: var(--shadow-md);
}

Diseño Responsive

Este boilerplate está completamente optimizado para ser responsive y se adapta automáticamente a diferentes tamaños de pantalla. El diseño funciona perfectamente en:

• Móviles (hasta 640px): Layout apilado verticalmente, navegación en columna, tipografía optimizada
• Tablets pequeñas (641px - 768px): Transición entre móvil y tablet, elementos reorganizados
• Tablets (769px - 1024px): Layout híbrido con más espacio horizontal
• Escritorio (1025px+): Layout completo con máximo aprovechamiento del espacio

Características responsive implementadas

1. Breakpoints definidos: Variables CSS para breakpoints estándar (--breakpoint-sm, --breakpoint-md, --breakpoint-lg, --breakpoint-xl)

2. Tipografía fluida: Uso de clamp() para tamaños de fuente que se adaptan automáticamente

3. Layout adaptativo:

   • Header que pasa de horizontal a vertical en móviles
   • Navegación que se apila en pantallas pequeñas
   • Contenedores con padding ajustado según el tamaño de pantalla

4. Cards responsive: Las cards se adaptan completamente, con padding y márgenes optimizados para cada dispositivo

5. Control de overflow: Prevención de scroll horizontal en todos los elementos mediante overflow-x: hidden y max-width: 100vw

6. Box-sizing consistente: border-box aplicado globalmente para cálculos de ancho precisos

Media queries disponibles

El proyecto utiliza media queries estándar para diferentes tamaños:

• @media (max-width: 480px) - Móviles muy pequeños
• @media (max-width: 640px) - Móviles
• @media (max-width: 768px) - Tablets pequeñas
• @media (max-width: 1024px) - Tablets

Todas las vistas y componentes creados heredan automáticamente estas características responsive, por lo que cualquier nueva funcionalidad que agregues se adaptará automáticamente a diferentes dispositivos.

Próximos pasos

Este boilerplate es un punto de partida sólido. Puedes extenderlo agregando:

• Más componentes reutilizables
• Nuevas vistas y rutas
• Personalización del Layout (navegación, menús, etc.)
• Gestión de estado (Context API, Zustand, Redux, etc.)
• Peticiones HTTP (fetch, axios, etc.)
• Autenticación y autorización
• Tests unitarios y de integración
• Temas personalizados o modo oscuro/claro manual