Publicar Nuxt con SSR: build de Node y comprobaciones

Nuxt puede generar archivos estáticos o ejecutar un servidor Node.js. La decisión depende de cómo usa tu aplicación rutas, datos y código de servidor: no elijas el modo estático solo para simplificar la publicación si eso elimina funciones que necesita tu web.

Esta guía prepara la salida Node de Nuxt con Nitro y explica qué revisar al conectarla a Hostbrid Projects. Projects admite servicios Node y contenedores según plan y recursos disponibles; revisa los límites y precios actuales antes de elegir. La guía no afirma que todos los módulos de Nuxt funcionen sin cambios.

Decide entre renderizado estático y servidor

nuxi generate prerenderiza rutas aptas y deja la salida pública en .output/public. El servidor Node es la opción para páginas que se renderizan por petición, endpoints del servidor o funciones que dependen de Nitro. Nuxt describe ambas rutas en su guía oficial de despliegue.

Revisa nuxt.config, package.json, los módulos y las rutas con defineEventHandler antes de cambiar el modo. Si el proyecto necesita peticiones del servidor, cookies o secretos disponibles solo en servidor, no sustituyas SSR por HTML estático sin comprobar cada función.

Genera y prueba el servidor Node

Conserva el lockfile y usa el gestor con el que se creó. Para un proyecto npm:

npm ci
npm run build
NODE_ENV=production node .output/server/index.mjs

El preset node-server de Nitro produce el punto de entrada .output/server/index.mjs; Nuxt documenta que escucha en el puerto 3000 por defecto y permite configurar PORT y HOST. En local, prueba PORT=3000 HOST=127.0.0.1 NODE_ENV=production node .output/server/index.mjs y comprueba la portada, una ruta dinámica y una URL inexistente. Usa el script build real de tu package.json; si apunta a otro comando, entiende el motivo antes de copiar estas instrucciones.

Mantén las variables privadas

Nuxt diferencia runtimeConfig privado de runtimeConfig.public. Las variables NUXT_PUBLIC_* se exponen al navegador y no deben contener contraseñas, claves de proveedor ni tokens administrativos. Define secretos en la configuración privada del servicio, no en Git ni en el código que se incluye en el bundle. La documentación de runtime config explica la correspondencia entre configuración y variables de entorno.

Publica y comprueba las rutas

Conecta el repositorio en Projects, selecciona la rama correcta y configura build, comando de arranque y runtime según el proyecto y el plan. Si el preset del servicio no coincide con el artefacto Nitro, aporta un Dockerfile que ejecute npm ci, npm run build y arranque node .output/server/index.mjs; configura el puerto que expone el contenedor. No copies una configuración genérica sin revisar la versión de Node y el package.json del repositorio.

Empieza con el dominio temporal. Comprueba SSR real, rutas con y sin barra final, assets, formularios, autenticación, llamadas a APIs y logs. Después configura el dominio final y repite las pruebas con HTTPS. Si solo necesitas páginas prerenderizadas, puedes comparar la salida estática con Sites y evitar mantener un proceso que no hace falta.

Comprobación local (9 de octubre de 2026): una app mínima de Nuxt 4.6.0 compiló con el preset node-server; node .output/server/index.mjs sirvió la portada con HTTP 200 y una ruta inexistente con HTTP 404. No se desplegó este ejemplo en una cuenta de Projects ni se probó compatibilidad de módulos de terceros.

Referencias: despliegue de Nuxt, configuración de runtime, Projects y sus planes vigentes.