341 lines
8.3 KiB
Markdown
341 lines
8.3 KiB
Markdown
********
|
||
# 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.
|