********
# Vite + React (frontend) — Guía básica para usar junto a Flask

> **Objetivo**: tener un frontend en **React + Vite** que puedas desarrollar con HMR y luego **construir** para servirlo desde Flask. Aquí nos enfocamos solo en **Vite/React** (no en Python), pero incluimos cómo se **orquesta** con un backend Flask a alto nivel.

---

## 1) Requisitos

* **Node.js** LTS (>= 18) — trae **npm** incluido.
* Un editor (VS Code recomendado).
* Terminal con `git` (opcional pero útil).

> Comprueba versiones: `node -v` y `npm -v`.

---

## 2) Crear un proyecto con Vite

**Con JavaScript**:

```bash
npm create vite@latest myapp -- --template react
cd myapp
npm install
npm run dev
```

**Con TypeScript** (recomendado para escalar):

```bash
npm create vite@latest myapp -- --template react-ts
cd myapp
npm install
npm run dev
```

* Vite arrancará en `http://localhost:5173/` (puerto por defecto).
* Para cambiar el puerto: `npm run dev -- --port 3000` o config en `vite.config.ts`.

---

## 3) Estructura de carpetas (frontend)

```
myapp/
├─ index.html               # HTML raíz (Vite lo usa como entry)
├─ package.json             # Scripts y dependencias
├─ vite.config.ts           # Config de Vite (plugins, proxy, alias, etc.)
├─ public/                  # Archivos copiados tal cual al build (opcional)
└─ src/
   ├─ main.tsx / main.jsx   # Punto de entrada de React
   ├─ App.tsx / App.jsx     # Componente raíz
   ├─ assets/               # Imágenes / fuentes estáticas importables
   ├─ components/           # Componentes reutilizables
   ├─ pages/                # Páginas si usas router
   └─ styles/               # CSS / CSS Modules / etc.
```

**Notas clave**

* `index.html` está en la **raíz** (no en `public/`). Vite lo procesa y resuelve `<script type="module" src="/src/main.tsx">`.
* Todo lo que pongas en `public/` se copia **sin procesar** al build final.
* Las imágenes en `src/assets` se **empaquetan** (hash/optimización) y se importan desde el código.

---

## 4) Scripts típicos en `package.json`

```json
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}
```

* `npm run dev` → servidor de desarrollo (HMR).
* `npm run build` → compila a `dist/`.
* `npm run preview` → sirve **lo construido** (por defecto en `http://localhost:4173`).

---

## 5) Comandos más usados de Vite

* **Desarrollo**: `vite` o `vite dev` (normalmente via `npm run dev`).
* **Compilar**: `vite build`.
* **Previsualizar build**: `vite preview`.
* Flags útiles:

  * `--port 3000` (puerto dev)
  * `--open` (abre el navegador)
  * `--host` (exponer en LAN)
  * `--base /subruta/` (si servirás el frontend bajo una subruta en producción)

---

## 6) Comandos básicos de **npm**

* **Instalar dependencias del proyecto**: `npm install`
* **Agregar librería**: `npm install <paquete>`
* **Agregar librería de dev** (tipos, linters, etc.): `npm install -D <paquete>`
* **Quitar librería**: `npm uninstall <paquete>`
* **Ejecutar scripts**: `npm run <script>`
* **Actualizar**: `npm update`

> También puedes usar **pnpm** o **yarn**, pero si no tienes preferencia, `npm` está perfecto.

---

## 7) Instalar librerías de React

Ejemplos comunes:

```bash
npm install react-router-dom         # Router
npm install axios                    # HTTP client
npm install zustand jotai            # Estado
npm install classnames               # Utilidades de clases CSS
```

> Si una librería marca conflicto de versiones de React (peer deps), verifica qué versión soporta. Si necesitas, fija React:

```bash
npm install react@18 react-dom@18    # si un paquete no soporta React 19 aún
```

---

## 8) Orquestación con Flask (visión general)

### Durante el desarrollo

* Levantas **dos servidores**:

  * Backend Flask (ej. `http://localhost:5000`)
  * Frontend Vite (ej. `http://localhost:5173`)
* Para evitar CORS en dev, usa el **proxy** de Vite y llama a `/api` desde React.

**`vite.config.ts`**

```ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://localhost:5000',  // Flask
        changeOrigin: true,
        // rewrite: (path) => path.replace(/^\/api/, ''), // si necesitas reescribir
      }
    }
  }
})
```

En React:

```ts
fetch('/api/users') // Vite lo proxya a Flask en dev
```

### En producción

* Ejecutas `npm run build` → se genera `dist/` (HTML, JS, CSS, assets).
* Flask **sirve** esos archivos (como estáticos) y envía `index.html` en rutas del SPA.
* Si servirás bajo una **subruta** (ej. `/app/`), configura `base` en Vite:

```ts
export default defineConfig({ base: '/app/' })
```

> *Aquí no detallamos Flask*, solo recuerda: apunta tu backend a los archivos de `dist/` y enruta al `index.html` para las rutas del SPA.

---

## 9) Archivos clave

### `index.html` (raíz)

```html
<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My App</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
```

### `src/main.tsx`

```tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './styles/main.css'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
)
```

### `src/App.tsx`

```tsx
export default function App() {
  return <h1>Hola, Vite + React</h1>
}
```

---

## 10) Variables de entorno

* Crea archivos `.env`, `.env.development`, `.env.production`.
* **Prefijo obligatorio**: `VITE_` para que sean visibles en el cliente.

`.env`

```
VITE_API_URL=/api
```

Uso en código:

```ts
const base = import.meta.env.VITE_API_URL
```

---

## 11) Aliases y rutas de importación

Configura `@` → `src` para imports limpios.

```ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'node:path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  }
})
```

Uso:

```ts
import Button from '@/components/Button'
```

---

## 12) CSS, CSS Modules y assets

* **CSS global**: importa `src/styles/main.css` en `main.tsx`.
* **CSS Modules**: `Button.module.css` → `import styles from './Button.module.css'`.
* **Imágenes** desde `src/assets`:

```tsx
import logo from '@/assets/logo.svg'
<img src={logo} alt="logo" />
```

* **Carpeta `public/`**: todo se copia sin procesar → accedes con `/archivo.ext`.

---

## 13) TypeScript (opcional)

* Usa plantilla `react-ts` para TS listo.
* Beneficios: autocompletado, tipado de props/estado, refactors más seguros.

---

## 14) Plugins útiles de Vite (opcionales)

* `@vitejs/plugin-react` (incluye Fast Refresh, JSX).
* `vite-tsconfig-paths` (respetar paths del `tsconfig` si usas TS).
* `@rollup/plugin-visualizer` (inspeccionar el bundle del build).

Instalar ej.:

```bash
npm install -D vite-tsconfig-paths @rollup/plugin-visualizer
```

---

## 15) Checklist de primeros pasos

1. Crear proyecto con `npm create vite@latest` (elige `react` o `react-ts`).
2. `npm install` y `npm run dev`.
3. Añadir **proxy** a Flask (`/api`) en `vite.config.ts`.
4. Crear componentes en `src/components` y páginas en `src/pages`.
5. Variables en `.env` con prefijo `VITE_`.
6. `npm run build` y servir el contenido de `dist/` desde Flask.

---

## 16) Troubleshooting rápido

* **Puerto 5173 ocupado**: `npm run dev -- --port 3000` o `server.port` en `vite.config.ts`.
* **CORS en dev**: usa `server.proxy` y llama a `/api` desde el frontend.
* **Conflictos de React (peer deps)**: si una librería soporta solo React 16–18, instala React 18:

  ```bash
  npm install react@18 react-dom@18
  ```
* **HMR no funciona**: asegúrate del `<script type="module" src="/src/main.tsx">` y que no sirves el HTML desde otro servidor en dev.
* **Servir bajo subruta**: fija `base: '/subruta/'` en `vite.config.ts` y configura Flask para servir en esa ruta.

---

## 17) Recursos (opcionales)

* Documentación oficial de Vite
* React Docs
* Guías de despliegue SPA con backends

> ¡Listo! Con esto tienes lo esencial para trabajar cómodo con **Vite + React** y conectarlo a un backend Flask sin dolores de cabeza.