Despliega tu aplicación Node.js en el hosting de Rivervo (Next.js y Nuxt).
Mucha gente da por hecho que las aplicaciones Node.js tienen que vivir en un VPS. No es así: todos los planes de hosting compartido de Rivervo tienen Node.js y Python en el menú del sitio web, que levanta un proceso de Phusion Passenger para tu aplicación detrás del mismo Apache que sirve tus otros sitios.
Esta guía recorre todo el proceso para los dos frameworks más habituales: Next.js y Nuxt 3. El resultado: tu aplicación en https://tudominio.com (o en cualquier subdominio), funcionando en un proceso Node.js real, que sobrevive a los reinicios y se puede reiniciar con un clic.
Si nunca has desplegado una aplicación Node en hosting compartido, donde todo el mundo se atasca es en el archivo de inicio: Passenger necesita un único script de entrada que arranque tu framework. Más abajo te damos uno para cada framework; copia y pega, sin cambios.
Qué necesitas antes de empezar
- Un plan de hosting de Rivervo (cualquiera: las aplicaciones Node.js funcionan en todos los planes)
- Node.js v20 o posterior en local para compilar tu aplicación
- La aplicación compilada, lista para subir (lo vemos para cada framework)
- Acceso a tu cuenta por el gestor de archivos o por SFTP (sirven los dos)
No necesitas root, sudo, systemd ni configurar un proxy inverso. Passenger se encarga de todo eso.
Paso 1: compila tu aplicación en local
Vas a subir la aplicación compilada, no el código fuente. El panel instala las dependencias, pero no compila React ni ejecuta una compilación de Vite. Hazlo antes en tu equipo.
Next.js:
npm ci
npm run buildEsto genera .next/ (el resultado compilado). No ejecutes next start aquí: la lanzaremos desde el archivo de inicio en un momento.
Nuxt 3:
npm ci
npm run buildEsto genera .output/ (el directorio de compilación universal de Nuxt). Lo mismo: no ejecutes nada todavía.
Paso 2: sube los archivos correctos
No hace falta subir node_modules/. El panel instala las dependencias por ti. Tampoco necesitas git ni las cachés de compilación.
Súbelos a tu cuenta, a ser posible a una ruta fuera de public_html (por ejemplo, /home/<cuenta>/myapp/). ¿Por qué fuera? Porque Passenger monta public_html en la raíz de la URL automáticamente, y poner ahí el código de tu aplicación lo deja expuesto.
| Framework | Sube esto | Omite |
|---|---|---|
| Next.js | .next/, public/, package.json, package-lock.json, next.config.js, tu server.cjs (abajo) | node_modules/, .git/, .env.local |
| Nuxt 3 | .output/, package.json, package-lock.json, tu server.cjs (abajo) | node_modules/, .nuxt/, .git/, el código fuente de pages/, components/ |
Hay dos formas de llevar los archivos:
- Sitio web → Archivos → sube un zip → descomprímelo: lo más fácil si tu conexión es inestable.
- SFTP (FileZilla, Cyberduck,
rsync): más rápido para despliegues repetidos. El servidor, el puerto, el usuario y la contraseña están en Sitio web → SSH y SFTP.
Paso 3: añade el archivo de inicio
Es el archivo que Passenger ejecuta cuando llega una petición. Ponlo junto a package.json en la carpeta de tu aplicación.
Para Next.js: server.cjs
const next = require('next')
const http = require('http')
const port = process.env.PORT || 3000
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev, dir: __dirname })
const handle = app.getRequestHandler()
app.prepare().then(() => {
http.createServer((req, res) => handle(req, res)).listen(port, () => {
console.log(`Next.js server listening on port ${port}`)
})
})Qué hace:
- Carga Next y lo apunta al directorio actual (donde están tu
.next/y tupackage.json). - Crea un gestor de peticiones a partir del enrutador interno de Next.
- Arranca un servidor HTTP en el puerto que asigna Passenger (
process.env.PORT). - Usa
3000como alternativa para las pruebas en local.
dev se deduce automáticamente de NODE_ENV: elige el modo Production en el panel (lo haremos en el paso 4) y Next se ejecuta en modo producción.
Para Nuxt 3: server.cjs
import('./.output/server/index.mjs').then(({ createApp }) => {
createApp().then(({ app }) => {
const port = process.env.PORT || 3000
app.listen(port, () => {
console.log(`Nuxt server listening on port ${port}`)
})
})
})Qué hace:
- Importa dinámicamente
.output/server/index.mjsde Nuxt (la entrada que generanpm run build). - Usa
createApp()para crear la instancia del servidor H3. - Escucha en el puerto que asigna Passenger.
El import() dinámico es intencionado: los módulos .mjs no se pueden cargar con require(), pero un archivo .cjs sí puede importarlos dinámicamente. Es el patrón más limpio que funciona dentro del lanzador de Passenger.
Paso 4: crea la aplicación en el panel
Abre tu proyecto → Sitio web → Node.js y Python → Aplicación Node.js.
| Campo | Valor |
|---|---|
| Versión | 20 o posterior |
| Modo | Production |
| Carpeta | myapp en tu carpeta personal (donde subiste los archivos) |
| Dirección | tudominio.com (o un subdominio como app.tudominio.com) |
| Archivo de inicio | server.cjs |
Pulsa Crear. Se crea un entorno Node.js en ~/nodevenv/myapp/20/.
Instala las dependencias
Cuando la aplicación esté creada, pulsa Instalar dependencias (npm install) en ella y sigue la salida. Si falla:
- Comprueba que
package.jsonestá en la raíz de la aplicación (no en una subcarpeta). - En Next.js: confirma que
nextestá endependencies, no endevDependencies(la instalación de producción omite las dependencias de desarrollo). - En Nuxt:
nuxttambién debe ser una dependencia normal.
Añade variables de entorno
En la aplicación, Ajustes → Variables de entorno → Añadir una variable. El modo Production ya define NODE_ENV=production.
Si tu aplicación Next.js lee valores en tiempo de ejecución (URL de bases de datos, claves de API), añádelos aquí. No subas un archivo .env con secretos: las variables de entorno de la aplicación son el lugar adecuado.
Al guardar los ajustes, la aplicación se reinicia y las nuevas variables se aplican al momento.
Paso 5: comprueba que funciona
Visita la URL de tu aplicación. Deberías ver tu aplicación.
Si ves una página de error de Passenger, despliégala y mira al final: casi siempre hay una traza de error clara. Las dos más habituales:
Error: Cannot find module 'next': npm install no se ejecutó o se ejecutó en la carpeta equivocada. Pulsa de nuevo Instalar dependencias (npm install).
Error: ENOENT: no such file or directory, open '.next/...': subiste el código fuente, pero no el directorio compilado .next/. Compila en local y vuelve a subirlo.
Cómo desplegar actualizaciones
Repite los pasos 1 y 2 y pulsa Reiniciar en la aplicación. En concreto:
1. Compila en local npm run build
2. Sube .next/ o .output/, más el código o la configuración que haya cambiado
3. Panel Reinicia la aplicaciónSi cambias package.json, pulsa Instalar dependencias (npm install) antes de reiniciar. ¿Prefieres la línea de comandos? En Sitio web → Terminal, la tarjeta de la aplicación muestra el comando para entrar en su entorno.
Problemas habituales
WebSockets: Passenger gestiona HTTP/1.1 y HTTP/2. La actualización a WebSocket funciona con las rutas integradas de Next.js y Nuxt. Si usas un servidor WebSocket aparte (ws, socket.io), comparte el mismo puerto y arranca desde el mismo server.cjs, sin configuración adicional.
Subida de archivos / límites de body-parser en next.config.js: el límite por defecto del cuerpo de las peticiones en Passenger es de 10 MB. Si subes archivos grandes, aumenta passenger_max_request_size con un .htaccess en public_html:
PassengerMaxRequestSize 52428800(50 MB en bytes).
Tareas cron: si tu aplicación necesita tareas en segundo plano (envíos de newsletter, exportaciones programadas), no las ejecutes dentro del proceso web. Usa Sitio web → Tareas cron para llamar directamente a un script de Node:
/home/<cuenta>/nodevenv/myapp/20/bin/node /home/<cuenta>/myapp/scripts/send-newsletter.jsMemoria del proceso: Passenger reinicia tu aplicación si supera el límite de RAM por cuenta (depende de tu plan). Una aplicación Next.js o Nuxt típica consume menos de 100 MB en reposo. Si llegas al límite, analiza con process.memoryUsage() y busca fugas antes de dar por hecho que necesitas un plan mayor.
Dominios propios y HTTPS: la dirección que configuras en la aplicación es la que usa Passenger. El SSL es automático, sin configuración adicional. Para otro dominio o un subdominio, añádelo primero en Sitio web → Dominios y luego elígelo como dirección de la aplicación.
Versión de Node: la lista Versión muestra todas las versiones instaladas; cámbiala en los Ajustes de la aplicación.
Cuándo no usar hosting compartido para Node
Para ser claros: Node.js en hosting compartido funciona de maravilla para portfolios, blogs, páginas de marketing, frontends de SaaS pequeños y herramientas internas. Se queda corto para:
- API con mucho volumen (más de 50 peticiones por segundo sostenidas): notarás el límite de CPU por cuenta
- Aplicaciones con mucho WebSocket y miles de conexiones simultáneas
- Aplicaciones que lanzan procesos de trabajo (workers de colas, scrapers): el límite de procesos por cuenta de Passenger lo complica
- Cualquier cosa que necesite systemd, Docker o acceso root
Para eso, nuestro VPS es la opción adecuada: root completo, tu propio kernel y ejecuta lo que quieras. Pero para la mayoría de las aplicaciones Next.js y Nuxt que no reciben un tráfico enorme, esta guía es todo lo que necesitas.
En resumen
npm run builden local- Sube
.next/(Next) o.output/(Nuxt) +package.json+server.cjs - Sitio web → Node.js y Python → Aplicación Node.js → la carpeta, archivo de inicio
server.cjs, modo Production - Instalar dependencias (npm install) y después Reiniciar
Si algo no va bien, abre un ticket: pega la página de error de Passenger y te señalaremos la línea.
— El equipo de Rivervo