Haz deploy de una app React (build con Vite)

Introducción

Para desarrollar y alojar una aplicación React en Square Cloud, es esencial seguir una secuencia estructurada de configuraciones y requisitos previos. Esta guía técnica cubrirá todo el proceso, desde la configuración inicial hasta el despliegue en producción.

Requisitos previos

Cuenta de Square Cloud: Regístrate a través de la página de registro usando tu correo electrónico.
Plan activo: Garantiza recursos dedicados y un rendimiento optimizado para tu aplicación. Consulta nuestros planes disponibles y elige el más adecuado para tus necesidades.

Esta guía usa el runtime estático o el runtime de Node.js. Probado con React 19 y Vite 8 en Node.js 24 en septiembre de 2026.

Crear el proyecto

Necesitas Node.js y npm en tu máquina. Si no los tienes, descárgalos desde el sitio oficial de Node.js. Crea un proyecto React con Vite:

npm create vite@latest my-react-app -- --template react

my-react-app es la carpeta del proyecto. Usa --template react-ts para TypeScript. El -- pasa la opción al inicializador en lugar de a npm. Luego instala las dependencias:

cd my-react-app
npm install

¿Usas React Router en modo framework, con renderizado en el servidor? Sigue la guía de React Router. ¿Usas Next.js? Sigue la guía de Next.js.

Compilar para producción

npm run build

Vite escribe los archivos de producción en la carpeta dist/.

Elegir cómo servirlo

Una app React compilada con Vite es un sitio estático: archivos HTML, CSS y JavaScript que cualquier servidor web puede entregar. Elige una de estas opciones:

Runtime estático (recomendado)
Servidor Express
Paquete serve

El runtime estático sirve los archivos de tu build con un servidor web gestionado por Square Cloud. No se ejecuta ningún proceso de Node.js, así que es la forma más ligera de alojar un sitio sin código del lado del servidor.

Compila el sitio

Ejecuta npm run build. La salida va a la carpeta dist.

Mantén funcionando las rutas del cliente

Si tu app cambia de página en el navegador sin recargar (enrutamiento del lado del cliente), renombra dist/index.html a vite.html. El runtime estático responde con vite.html a toda ruta que no sea un archivo, así que recargar una ruta como /about sigue cargando tu app. Un sitio con un archivo HTML por página conserva index.html: las rutas desconocidas devuelven entonces tu 404.html. Consulta cómo sirve los archivos el runtime estático.

Añade el archivo de configuración

Crea un archivo squarecloud.app dentro de dist. Un MAIN que apunta a un archivo HTML selecciona el runtime estático:

squarecloud.app

MAIN=vite.html
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My website
SUBDOMAIN=mywebsite

Usa MAIN=index.html si conservaste index.html. 512 MB es la memoria mínima para un sitio web. Cuando subes por el dashboard, te pide estos valores y escribe el archivo por ti.

Comprime la salida del build

Comprime el contenido de dist, no la carpeta en sí, para que squarecloud.app quede en la raíz del ZIP. Con la CLI, ejecuta squarecloud upload desde dentro de dist.

Todo lo que está en el ZIP es público en tu sitio. Sube solo la salida del build, nunca tu código fuente ni archivos .env.

La mayoría de las herramientas de build vacían dist en cada build. Guarda una copia de squarecloud.app en la carpeta que tu framework copia sin cambios al build (public/ en proyectos basados en Vite), o repite los tres últimos pasos después de cada build.

Esta opción ejecuta un pequeño servidor Express en el runtime de Node.js. Instala Express como dependencia normal, no como devDependency, porque Square Cloud no instala las devDependencies:

npm install express

Crea un archivo server.mjs en la raíz de tu proyecto. Sirve la carpeta de salida del build, dist, y devuelve index.html para cualquier otra ruta, así el enrutamiento del lado del cliente sigue funcionando:

server.mjs

import express from 'express';
import path from 'node:path';

const app = express();
const distPath = path.join(import.meta.dirname, 'dist');

app.use(express.static(distPath));

// SPA fallback: serve index.html for any route not matched above
app.use((req, res) => {
  res.sendFile(path.join(distPath, 'index.html'));
});

// Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container
const port = Number(process.env.PORT) || 80;
app.listen(port, '0.0.0.0', () => console.log(`Server running on port ${port}`));

Para probarlo en tu máquina, elige un puerto libre: PORT=3000 node server.mjs.Crea un archivo squarecloud.app en la raíz de tu proyecto. Square Cloud inicia tu sitio con node server.mjs:

squarecloud.app

MAIN=server.mjs
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My website
SUBDOMAIN=mywebsite

Ejecuta npm run build antes de crear tu ZIP. El ZIP necesita server.mjs, package.json, squarecloud.app y la carpeta dist, sin node_modules: Square Cloud instala tus dependencias en el primer inicio. Las herramientas de build suelen ser devDependencies, que Square Cloud no instala, así que el build tiene que ejecutarse en tu máquina.

Esta opción ejecuta el paquete serve en el runtime de Node.js, sin escribir código de servidor. Instálalo como dependencia normal:

npm install serve

Añade un script start:prod a los scripts de tu package.json, junto a los que ya tienes:

package.json

"scripts": {
  "start:prod": "serve -s dist"
}

serve -s dist sirve la carpeta de salida del build, dist, en modo de página única: cualquier ruta que no sea un archivo devuelve index.html, así el enrutamiento del lado del cliente sigue funcionando. serve escucha en todas las interfaces de red, en el puerto de la variable de entorno PORT, que Square Cloud define como 80 (en local usa 3000).Crea un archivo squarecloud.app en la raíz de tu proyecto:

squarecloud.app

RUNTIME=nodejs
START=npm run start:prod
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My website
SUBDOMAIN=mywebsite

RUNTIME=nodejs selecciona el runtime de Node.js sin necesidad de un archivo MAIN, y START reemplaza el comando de inicio predeterminado.Ejecuta npm run build antes de crear tu ZIP. El ZIP necesita package.json, squarecloud.app y la carpeta dist, sin node_modules: Square Cloud instala tus dependencias en el primer inicio. Las herramientas de build suelen ser devDependencies, que Square Cloud no instala, así que el build tiene que ejecutarse en tu máquina.

Hacer deploy y verificar

Crea el ZIP descrito en la opción que elegiste y súbelo:

A través del panel

Accede a la página de subida

Accede a la página de subida y sube el archivo zip de tu proyecto.

Configura tu entorno

Después de subir tu zip, deberás configurar el nombre, el archivo principal o el entorno de ejecución y otros ajustes de tu proyecto.
Si estás subiendo un proyecto web, asegúrate de seleccionar “Publicación Web” y de definir un subdominio para tu proyecto.

Despliega tu proyecto

Por último, haz clic en el botón “Deploy” para alojar tu proyecto en Square Cloud.
Tras el despliegue, puedes monitorear el estado y los logs de tu proyecto desde el panel.

Confirma que tu aplicación esté en vivo

Tu primer despliegue suele tardar menos de un minuto. En el dashboard, espera a que el estado de tu aplicación muestre “running” y revisa los logs por si hay errores de inicio.
Si desplegaste un sitio web o una API, abre https://<tu-subdominio>.squareweb.app en tu navegador: deberías ver tu aplicación respondiendo. Si desplegaste un bot, envíale un comando para confirmar que esté online.

¿La aplicación no inicia? Consulta la guía de solución de problemas para ver las causas y soluciones más comunes.

A través de la CLI

Para usar este método, tu proyecto necesita un archivo de configuración llamado squarecloud.app en su raíz. Le indica a Square Cloud cómo ejecutar tu aplicación.

Guía del archivo de configuración

Aprende a crear el archivo de configuración squarecloud.app que define el entorno de tu aplicación.

Instala la CLI

Instala la CLI de Square Cloud. Si ya la tienes, ejecuta el mismo comando para actualizarla:

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

Inicia sesión

Ejecuta el comando de abajo. Abre tu navegador: aprueba el inicio de sesión allí y la CLI queda lista. No hay ninguna clave de API que copiar. Para scripts y CI, consulta autenticación de la CLI.

squarecloud auth login

Sube tu proyecto

Desde la carpeta de tu proyecto, ejecuta el comando de abajo. La CLI comprime la carpeta actual en un zip, dejando fuera lo que lista squarecloud.ignore, y lo sube:

squarecloud upload

Para subir un zip que creaste tú mismo, pásalo con --file:

squarecloud upload --file <path/to/zip>

Confirma que tu aplicación esté en vivo

Tu primer despliegue suele tardar menos de un minuto. Revisa el estado y los logs de tu aplicación directamente desde la terminal:

squarecloud app status
squarecloud app logs

Si desplegaste un sitio web o una API, abre https://<tu-subdominio>.squareweb.app en tu navegador: deberías ver tu aplicación respondiendo. Si desplegaste un bot, envíale un comando para confirmar que esté online.

¿La aplicación no inicia? Consulta la guía de solución de problemas para ver las causas y soluciones más comunes.

Errores comunes

Dominio personalizado

Para usar un dominio personalizado (por ejemplo, mysite.com) en lugar de la URL predeterminada mysite.squareweb.app, necesitas el plan Standard o superior. La URL predeterminada sale del campo SUBDOMAIN del archivo de configuración. Para conectar tu dominio, sigue cómo configurar tu propio dominio.

Requisitos mínimos de RAM

Mínimo: 512MB de RAM para sitios web y APIs, suficiente para un build estático en el runtime estático. Para apps que renderizan páginas en un servidor (Next.js, Nuxt, Angular SSR y similares), recomendamos al menos 1GB de RAM. Para aplicaciones más grandes, asigna más RAM para evitar que la aplicación se quede sin memoria y falle.

No se pudo encontrar este sitio.

Verifica que el subdominio/dominio coincida con lo configurado en el campo SUBDOMAIN o en la configuración del dominio personalizado. Si acabas de subir el sitio, espera hasta 60 segundos para que Square habilite el primer acceso.

El sitio tardó demasiado en responder…

Tu servidor debe escuchar en el puerto 80 y el host 0.0.0.0. Square Cloud define las variables de entorno PORT (80) y HOST (0.0.0.0) en tu aplicación: léelas en tu código en lugar de fijar otros valores. Un servidor que escucha solo en localhost o 127.0.0.1 nunca recibe solicitudes.

Recargar una ruta devuelve 404

Tu app usa enrutamiento del lado del cliente, por ejemplo con React Router en modo declarativo, y el servidor no conoce la ruta. En el runtime estático, renombra index.html a vite.html. Las opciones de Express y serve de arriba ya devuelven index.html para las rutas desconocidas.

Próximos pasos

Variables de entorno

Mantén secretos y ajustes fuera de tu código y léelos en tiempo de ejecución.

Dominio personalizado

Sirve tu app en tu propio dominio, desde el plan Standard.

Solución de problemas

Arregla una app que no inicia o un sitio que no responde.

Para saber más sobre React, consulta la documentación oficial de React.

Contáctanos

Si continúas enfrentando dificultades técnicas, nuestro equipo de soporte especializado está disponible para ayudarte. Contáctanos y estaremos encantados de ayudarte a resolver cualquier problema: la calidad del soporte es una gran parte de por qué los desarrolladores califican a Square Cloud con 4.9/5 en 402 reseñas en Google y Trustpilot.

Bots

Sitios web

APIs y backends

Bases de datos

Aplicaciones autoalojadas

Guías

Guías de migración

Haz deploy de una app React (build con Vite)

Introducción

Requisitos previos

Crear el proyecto

Compilar para producción

Elegir cómo servirlo

Hacer deploy y verificar

A través del panel

A través de la CLI

Guía del archivo de configuración

Errores comunes

Dominio personalizado

Requisitos mínimos de RAM

No se pudo encontrar este sitio.

El sitio tardó demasiado en responder…

Recargar una ruta devuelve 404

Próximos pasos

Variables de entorno

Dominio personalizado

Solución de problemas

Contáctanos

​Introducción

​Requisitos previos

​Crear el proyecto

​Compilar para producción

​Elegir cómo servirlo

​Hacer deploy y verificar

​A través del panel

​A través de la CLI

Guía del archivo de configuración

​Errores comunes

​Dominio personalizado

​Requisitos mínimos de RAM

​No se pudo encontrar este sitio.

​El sitio tardó demasiado en responder…

​Recargar una ruta devuelve 404

​Próximos pasos

Variables de entorno

Dominio personalizado

Solución de problemas

​Contáctanos

Introducción

Requisitos previos

Crear el proyecto

Compilar para producción

Elegir cómo servirlo

Hacer deploy y verificar

A través del panel

A través de la CLI

Errores comunes

Dominio personalizado

Requisitos mínimos de RAM

No se pudo encontrar este sitio.

El sitio tardó demasiado en responder…

Recargar una ruta devuelve 404

Próximos pasos

Contáctanos