Instalar React con Vite
Le explicamos cómo crear un proyecto de React y TypeScript con Vite, ejecutar el servidor de desarrollo, compilarlo, publicarlo y resolver los errores más comunes.
Aurora YazılımEquipo editorial
6 min de lectura
Para instalar React con Vite, primero instale la última versión LTS de Node.js. Después, en el terminal, ejecute el comando npm create vite@latest, indique el nombre del proyecto y elija la plantilla de React con TypeScript. Entre en la carpeta del proyecto, instale las dependencias con npm install e inicie el servidor de desarrollo con npm run dev; el sitio se abre por defecto en localhost:5173.
Qué es Vite y por qué elegirlo
Vite es una herramienta de compilación y servidor de desarrollo pensada para proyectos web modernos. Durante el desarrollo sirve el código con el soporte nativo de módulos ES del navegador y solo procesa el archivo solicitado. Por eso, aunque el proyecto crezca, el servidor arranca en segundos y los cambios que guarda se reflejan en pantalla sin recargar la página.
En la fase de publicación, Vite empaqueta su código minificado, dividido en fragmentos y con nombres de archivo aptos para la caché. Ofrece plantillas listas para bibliotecas como React, Vue o Svelte y se ha convertido en uno de los puntos de partida más habituales en el ecosistema de React.
Vite como alternativa a Create React App
Durante muchos años los proyectos de React se iniciaban con Create React App. El equipo de React ya no recomienda esta herramienta para proyectos nuevos; la documentación oficial aconseja empezar con un framework (como Next.js) o con una herramienta de compilación como Vite. Si busca una alternativa a Create React App, Vite es la vía de transición más rápida y con menos configuración.
Si necesita generación de páginas en el servidor, enrutamiento basado en archivos y una salida de páginas lista para SEO, consulte nuestra guía de instalación de Next.js. Para un panel de administración, una herramienta interna o una aplicación de una sola página (SPA), Vite suele ser una opción más sencilla.
Requisitos previos
El único requisito previo real de Vite es Node.js. Las nuevas versiones de Vite dejan de dar soporte a versiones antiguas de Node, por lo que lo más seguro es instalar la última versión LTS desde nodejs.org. npm viene incluido con Node.js.
- La última versión LTS de Node.js y el npm que la acompaña.
- Un editor de código; para la instalación y las extensiones recomendadas, consulte el artículo sobre la instalación de VS Code.
- Terminal: PowerShell o Windows Terminal en Windows, Terminal en macOS y el shell de su preferencia en Linux.
- Opcional: Git para el control de versiones.
Node.js según el sistema operativo
Puede descargar e instalar Node.js desde nodejs.org. Si va a usar versiones distintas de Node en varios proyectos, elegir un gestor de versiones le facilitará el trabajo más adelante.
Windows
Descargue el instalador LTS desde nodejs.org e instálelo con las opciones por defecto, o utilice winget en PowerShell. Tras la instalación, cierre y vuelva a abrir el terminal para que se actualice el PATH.
winget install OpenJS.NodeJS.LTS
node -v
npm -vmacOS
Puede usar el paquete de instalación oficial o, si tiene Homebrew instalado, instalarlo con un solo comando.
brew install node
node -v
npm -vLinux
La versión de Node de los repositorios de las distribuciones suele estar anticuada. Instalarlo a nivel de usuario con nvm le da la versión actual y elimina la necesidad de sudo; después de instalar nvm con el script de instalación de su propia página de GitHub, ejecute los siguientes comandos.
nvm install --lts
nvm use --lts
node -vPasos para crear un proyecto React
Con Node.js listo, la creación del proyecto React es igual en todos los sistemas operativos. El comando le guía de forma interactiva: pregunta el nombre del proyecto, el framework (React) y la variante (TypeScript). Si prefiere indicar la plantilla directamente en el comando, utilice el formato siguiente; en npm, los parámetros adicionales se escriben después de dos guiones.
- Si prefiere trabajar con JavaScript, el nombre de la plantilla es react; para TypeScript, react-ts.
- Abra en el navegador la dirección que aparece en la línea Local del terminal (por defecto, localhost:5173).
- Cambie un texto en el archivo src/App.tsx y guarde; si la página se actualiza sin recargarse, el HMR (sustitución de módulos en caliente) funciona.
npm create vite@latest benim-uygulamam -- --template react-ts
cd benim-uygulamam
npm install
npm run devpnpm create vite benim-uygulamam --template react-ts
yarn create vite benim-uygulamam --template react-tsConozca la estructura del proyecto
La primera diferencia que llama la atención en un proyecto de Vite es que el archivo index.html está en el directorio raíz. Vite lo usa como punto de entrada, y la etiqueta script que contiene llama al archivo src/main.tsx.
| Archivo / carpeta | Función |
|---|---|
| index.html | La página de entrada de la aplicación; aquí van el título y las metaetiquetas |
| src/main.tsx | El archivo inicial que conecta React con la página |
| src/App.tsx | El componente principal; desde aquí construye sus propias páginas |
| public/ | Archivos que se copian sin procesar: favicon, robots.txt |
| vite.config.ts | Plugins, alias y ajustes del servidor y del build |
| package.json | Dependencias y scripts de dev, build y preview |
Variables de entorno
Vite solo pasa al código del cliente las variables que empiezan por el prefijo VITE_, y se accede a ellas mediante import.meta.env. Estas variables quedan incrustadas en el paquete que llega al navegador; nunca ponga aquí datos como claves secretas de API, guárdelas en el lado del servidor.
VITE_API_URL=https://api.ornek.comCompilar y publicar
El servidor de desarrollo es solo para el trabajo local. La versión que publicará se genera con npm run build; la salida se escribe en la carpeta dist. npm run preview permite probar localmente esa salida de forma muy parecida a la publicación real.
La carpeta dist se compone de archivos HTML, CSS y JavaScript sin más; puede subirse a cualquier alojamiento estático o a un servidor web como Nginx. Para la velocidad es importante servir los archivos comprimidos y con cabeceras de caché de larga duración; explicamos estos ajustes en detalle en nuestra página de velocidad y rendimiento.
- Si la aplicación se va a publicar en una subcarpeta (ejemplo.com/panel/), establezca la opción base de vite.config.ts con esa ruta.
- Si usa React Router, añada en el servidor una regla que redirija todas las direcciones desconocidas a index.html.
- En las páginas de contenido que deben aparecer en los buscadores, el renderizado solo en el cliente puede quedarse corto; en ese punto cobra importancia el enfoque del diseño web SEO.
npm run build
npm run previewErrores frecuentes y soluciones
La mayoría de los errores que aparecen al instalar Vite se deben a la versión de Node, al puerto o a los ajustes de publicación. La tabla siguiente resume los casos más frecuentes; para más comandos, consulte la guía de comandos de npm.
| Síntoma | Por qué | Solución |
|---|---|---|
| Aviso «Vite requires Node.js version...» | Versión antigua de Node | Pase a la última versión LTS |
| Port 5173 is in use | El puerto está abierto en otro proceso | Vite prueba con el puerto siguiente; para fijar el puerto, utilice el ajuste server.port |
| No se encuentra el comando node | El PATH no se ha actualizado | Cierre y vuelva a abrir el terminal; si hace falta, reinicie el ordenador |
| Página en blanco tras publicar | Ruta base incorrecta | Corrija el ajuste base según la carpeta de publicación |
| Error 404 al recargar la página | Falta el enrutamiento SPA en el servidor | Redirija todas las rutas a index.html |
Próximos pasos
Una vez que tenga un proyecto en marcha, puede añadir herramientas como React Router para el enrutamiento, TanStack Query para la obtención de datos y Tailwind CSS o CSS Modules para los estilos. Para la calidad del código, amplíe según su proyecto la configuración de ESLint que viene con la plantilla.
La pareja Vite y React ofrece una base sólida para aplicaciones de negocio como paneles de reservas, pantallas de stock, seguimiento de citas o gestión de cartas QR. En este tipo de productos, además de la interfaz, también son decisivos el modelo de datos, la autorización y las copias de seguridad; si prefiere avanzar sobre una infraestructura ya lista, las soluciones de software para su sector pueden ahorrarle tiempo.
Tan importante como la infraestructura técnica es la estructura de la interfaz: planificar el flujo del usuario y la disposición de las pantallas antes de escribir los componentes es la base del proceso de diseño UI/UX. Pensar en los puntos de ruptura móviles desde el principio también es mucho más barato, desde el punto de vista del diseño responsive, que corregirlos después.
Preguntas frecuentes
01¿Es obligatorio TypeScript en un proyecto de React con Vite?
No, la plantilla react funciona con JavaScript puro. Sin embargo, en proyectos medianos y grandes TypeScript detecta errores mientras se escribe y facilita el trabajo en equipo. La migración posterior es posible, pero empezar con react-ts desde el principio genera menos trabajo.
02¿Puedo migrar a Vite mi proyecto actual de Create React App?
Sí. Los pasos básicos son llevar index.html al directorio raíz, instalar Vite y el plugin de React en lugar de react-scripts y cambiar las variables con prefijo REACT_APP_ al prefijo VITE_. En proyectos grandes, pruébelo primero en una rama aparte y ejecute las pruebas.
03¿Un sitio hecho con Vite es suficiente para el SEO?
Para paneles y pantallas de aplicación no hay problema. En las páginas de contenido que deben posicionarse en los buscadores es más recomendable generar el contenido como HTML en el servidor; para ello se opta por un framework como Next.js o por una solución de prerenderizado.
04¿Debería usar pnpm en lugar de npm?
pnpm aprovecha mejor el espacio en disco y acelera la instalación; Vite funciona sin problemas con ambos gestores de paquetes. Que todo el equipo use la misma herramienta es más importante que cuál elija.
Instalar React con Vite es cuestión de unos minutos; el verdadero esfuerzo está en la arquitectura de la aplicación que construirá encima. Si necesita un panel, un sistema de reservas o un software de gestión a medida para su negocio, conozca nuestras soluciones de software para cada sector y, para un sitio rápido y único, nuestro servicio de diseño web.
