8.3 KiB

Raw Blame History

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:

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

Con TypeScript (recomendado para escalar):

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`

{
  "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:

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:

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

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:

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:

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)

<!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`

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`

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:

const base = import.meta.env.VITE_API_URL

11) Aliases y rutas de importación

Configura @ → src para imports limpios.

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:

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:

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.:

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

15) Checklist de primeros pasos

Crear proyecto con npm create vite@latest (elige react o react-ts).
npm install y npm run dev.
Añadir proxy a Flask (/api) en vite.config.ts.
Crear componentes en src/components y páginas en src/pages.
Variables en .env con prefijo VITE_.
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:
```
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.

8.3 KiB Raw Blame History Unescape Escape