Cómo hospedar una app Next.js

Ejecutar npm run dev en tu equipo es solo el comienzo. Para que otras personas accedan al sitio, Next.js debe compilarse para producción y quedar en un servidor siempre encendido, con el puerto, las variables y la versión de Node correctos.

Next.js no depende de ninguna plataforma concreta. La documentación oficial describe tres formas de hospedarlo: un servidor Node.js, una imagen Docker o archivos HTML estáticos. Cuál te conviene depende de las funciones de servidor que use tu proyecto.

¿Qué modo de hospedaje elegir?#

Elige la exportación estática solo si el sitio funciona sin código en el servidor. La documentación enumera lo que no se admite en ese modo: Server Actions, cookies, rewrites, redirects y headers de next.config, proxy (antes middleware), ISR, Draft Mode, rutas dinámicas sin generateStaticParams() y el optimizador de imágenes por defecto. Si usas alguno, quédate con el servidor Node.js. Para entender el formato estático en general, consulta qué es un sitio estático.

¿Qué necesitas antes de empezar?#

• Una versión reciente de Node.js. La documentación de Next.js indica el mínimo que exige. En producción, usa la versión LTS activa de Node.js; el calendario oficial muestra cuál es.
• Scripts en package.json, que create-next-app ya genera:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

• Un lockfile en el repositorio (package-lock.json, pnpm-lock.yaml) para instalar las mismas versiones en cualquier máquina.
• Un lugar donde ejecutarlo: un VPS, un contenedor o una plataforma de hospedaje. La diferencia está en VPS vs plataforma en la nube.

¿Cómo hospedarlo como servidor Node.js?#

Es el camino que admite todas las funciones. En el servidor (o en CI), ejecuta:

npm ci
npm run build
npm run start

next build crea la carpeta .next y muestra una tabla de rutas, donde ○ es estática y ƒ se renderiza bajo demanda. next start levanta el servidor de producción en 0.0.0.0, puerto 3000 por defecto. Para cambiar el puerto, usa la variable PORT o la opción -p:

PORT=8080 npm run start
npx next start -p 8080

PORT debe estar en el entorno del proceso. Ponerla en .env no funciona, porque el servidor HTTP arranca antes de que Next.js cargue ese archivo.

Con next start, la optimización de imágenes de next/image funciona sin configuración. En Linux basado en glibc, la documentación advierte que puede requerir un ajuste del asignador de memoria para evitar un uso excesivo de RAM.

¿Cómo generar standalone o una exportación estática?#

Standalone, para un deploy más pequeño#

El modo standalone copia solo los archivos que el servidor realmente usa, incluidas las partes necesarias de node_modules. Actívalo en next.config.ts:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
};

export default nextConfig;

Tras next build, la carpeta .next/standalone incluye un server.js mínimo. No copia public ni .next/static por defecto. Cópialos tú:

npm run build
cp -r public .next/standalone/
cp -r .next/static .next/standalone/.next/
node .next/standalone/server.js

server.js lee PORT y HOSTNAME:

PORT=8080 HOSTNAME=0.0.0.0 node .next/standalone/server.js

En monorepos, el rastreo de archivos parte de la carpeta del proyecto. Si faltan archivos que están fuera de ella, define outputFileTracingRoot en next.config. Para empaquetar todo en una imagen, consulta cómo poner una app en Docker.

Exportación estática, para sitios sin código en el servidor#

Si el sitio es solo contenido, cambia la configuración:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",
};

export default nextConfig;

next build pasa a crear la carpeta out con un HTML por ruta, más CSS y JS. Cualquier servidor de archivos estáticos puede servirla. Si usas next/image, define un loader personalizado en images, ya que el optimizador por defecto necesita un servidor.

¿Cómo configurar las variables de entorno?#

Por defecto, las variables solo están disponibles en el servidor. Las que empiezan por NEXT_PUBLIC_ se insertan en el JavaScript durante next build: cambiar el valor después obliga a compilar de nuevo. En cambio, las variables leídas en el servidor durante el renderizado dinámico (por ejemplo, tras await connection()) se evalúan en tiempo de ejecución, así que un mismo build sirve para varios entornos.

Nunca pongas secretos en variables NEXT_PUBLIC_, porque llegan al navegador. El patrón general está en qué son las variables de entorno.

¿Cómo verificar que funcionó?#

1. Logs: next start imprime la dirección y el puerto, sin errores a continuación.
2. Petición: abre la página de inicio y una ruta dinámica en la dirección pública.
3. Assets: en el navegador, confirma que los archivos de /_next/static/ cargan con estado 200.
4. Reinicio: reinicia el proceso y comprueba que el sitio vuelve solo. El servidor de Next.js termina las peticiones en curso al recibir SIGTERM o SIGINT.

Si hay un proxy inverso como nginx delante, desactiva el buffering para que el streaming funcione (por ejemplo, con el header X-Accel-Buffering: no).

¿Cuáles son los errores más comunes?#

• El sitio abre en local pero no por la dirección pública: comprueba el host y el puerto en que escucha el proceso. next start ya escucha en 0.0.0.0 por defecto, pero el server.js de standalone escucha en la dirección de la variable HOSTNAME. Define HOSTNAME=0.0.0.0 y PORT en el comando de inicio.
• Página sin CSS o imágenes rotas en standalone: olvidaste copiar public y .next/static.
• Failed to find Server Action: con varias instancias, cada build genera su propia clave de cifrado. Define la misma NEXT_SERVER_ACTIONS_ENCRYPTION_KEY en todas, al compilar.
• Variable NEXT_PUBLIC_ con un valor antiguo: quedó incrustada en el build. Compila de nuevo.
• Proceso terminado durante next build: suele ser falta de memoria. Dale más RAM o compila fuera del servidor, en CI.
• Contenido desactualizado con más de una instancia: la caché de páginas vive en el disco de cada instancia. Para compartirla, configura un cache handler, como describe la documentación.

Cómo hacerlo en Square Cloud#

En Square Cloud el deploy es self-service: subes el proyecto y controlas la configuración. Node.js está entre diversos runtimes, y el runtime de sitios estáticos es una opción para la carpeta out de la exportación: en él nginx está siempre en línea sirviendo los archivos, sin código tuyo ejecutándose en el servidor. Puedes desplegar con subida de ZIP en el panel, la CLI, GitHub (un push despliega) o la extensión de VS Code.

La plataforma no tiene etapa de build. Ejecuta next build en un CI externo, como GitHub Actions, y sube el resultado, o pon el build en el comando de inicio: npm run build && npm start. En ese caso, todo lo que use el build tiene que estar en dependencies, porque las devDependencies no se instalan. El servidor debe escuchar en 0.0.0.0, en el puerto de la variable PORT, que next start ya lee.

El archivo squarecloud.app (nombre, archivo principal, memoria y versión) es opcional: el panel lo genera al desplegar, o puedes escribirlo en la raíz del proyecto. Las variables de entorno se definen por aplicación, en el panel, la API, la CLI o VS Code. El panel importa un .env, y el cambio se aplica en el siguiente reinicio, salvo en las NEXT_PUBLIC_, que solo cambian con un nuevo next build.

La aplicación corre en un contenedor siempre encendido. El reinicio automático viene activado al desplegar desde el panel y solo actúa cuando el proceso termina con error. La RAM del plan es un pool compartido entre tus aplicaciones, con un mínimo de 512 MB por aplicación web.

Toda aplicación web recibe un subdominio *.squareweb.app con HTTPS, y el dominio personalizado está disponible desde el plan Standard (consulta cómo usar un dominio personalizado). Los planes son de pago, empiezan en R$12,49 al mes y todos incluyen analítica web sin cookies. Los detalles están en la página de sitios.