Pubblica la tua app Node.js sull'hosting Rivervo (Next.js e Nuxt).
Molti pensano che le app Node.js debbano per forza stare su un VPS. Non è così: ogni piano di hosting condiviso Rivervo ha Node.js e Python nel menu del sito web, che avvia un processo Phusion Passenger per la tua app dietro lo stesso front-end Apache che serve gli altri tuoi siti.
Questa guida segue l'intero percorso per i due framework più diffusi: Next.js e Nuxt 3. Il risultato finale: la tua app su https://tuodominio.it (o su qualsiasi sottodominio), in esecuzione su un vero processo Node.js, che sopravvive ai riavvii e si riavvia con un clic.
Se non hai mai pubblicato un'app Node su un hosting condiviso, il punto in cui tutti si bloccano è il file di avvio: Passenger ha bisogno di un unico script di ingresso che avvii il framework. Qui sotto ne trovi uno per ogni framework: copia e incolla, senza modifiche.
Cosa ti serve prima di iniziare
- Un piano di hosting Rivervo (qualsiasi livello: le app Node.js funzionano su tutti i piani)
- Node.js v20 o più recente in locale per compilare l'app
- L'app compilata, pronta da caricare (vediamo come per ogni framework)
- Accesso al tuo account tramite File Manager o SFTP (vanno bene entrambi)
Non ti servono root, sudo, systemd o una configurazione di reverse proxy. A tutto questo pensa Passenger.
Passo 1: compila l'app in locale
Caricherai un'app compilata, non il sorgente. Il pannello installa le dipendenze, ma non compila React né esegue una build di Vite. Fallo prima sul tuo computer.
Next.js:
npm ci
npm run buildQuesto genera .next/ (il risultato della build). Non lanciare next start qui: l'app la avvieremo tra poco dal file di avvio.
Nuxt 3:
npm ci
npm run buildQuesto genera .output/ (la cartella di build universale di Nuxt). Stessa cosa: per ora non avviare niente.
Passo 2: carica i file giusti
Non serve caricare node_modules/. Le dipendenze le installa il pannello. Non servono nemmeno git o le cache di build.
Caricali nel tuo account, meglio in un percorso fuori da public_html (per esempio /home/<account>/myapp/). Perché fuori? Perché Passenger monta public_html automaticamente alla radice dell'URL, e mettere lì il codice dell'app lo rende accessibile a tutti.
| Framework | Carica questi | Salta |
|---|---|---|
| Next.js | .next/, public/, package.json, package-lock.json, next.config.js, il tuo server.cjs (sotto) | node_modules/, .git/, .env.local |
| Nuxt 3 | .output/, package.json, package-lock.json, il tuo server.cjs (sotto) | node_modules/, .nuxt/, .git/, il sorgente pages/, components/ |
Due modi per portare lì i file:
- Sito web → File → carica uno zip → estrailo è il modo più semplice se la tua connessione è instabile.
- SFTP (FileZilla, Cyberduck,
rsync) è più veloce per i deploy ripetuti. Server, porta, utente e password sono in Sito web → SSH e SFTP.
Passo 3: aggiungi il file di avvio
È il file che Passenger esegue quando arriva una richiesta. Mettilo accanto a package.json nella cartella dell'app.
Per 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}`)
})
})Cosa fa:
- Carica Next e lo punta alla cartella corrente (dove si trovano
.next/epackage.json). - Crea un gestore delle richieste dal router interno di Next.
- Avvia un server HTTP sulla porta assegnata da Passenger (
process.env.PORT). - Usa
3000come porta di riserva per i test in locale.
dev viene ricavato automaticamente da NODE_ENV: imposta la modalità Produzione nel pannello (lo facciamo nel Passo 4) e Next gira in modalità di produzione.
Per 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}`)
})
})
})Cosa fa:
- Importa dinamicamente
.output/server/index.mjsdi Nuxt (il punto di ingresso generato danpm run build). - Usa
createApp()per creare l'istanza del server H3. - Resta in ascolto sulla porta assegnata da Passenger.
L'import() dinamico è voluto: i moduli .mjs non si possono caricare con require(), ma un file .cjs può importarli dinamicamente. È lo schema più pulito che funziona dentro il launcher di Passenger.
Passo 4: crea l'applicazione nel pannello
Apri il tuo progetto → Sito web → Node.js e Python → Applicazione Node.js.
| Campo | Valore |
|---|---|
| Versione | 20 o più recente |
| Modalità | Produzione |
| Cartella | myapp nella tua cartella home (dove hai caricato i file) |
| Indirizzo | tuodominio.it (o un sottodominio come app.tuodominio.it) |
| File di avvio | server.cjs |
Clicca Crea. Viene creato un ambiente Node.js in ~/nodevenv/myapp/20/.
Installa le dipendenze
Una volta creata l'app, clicca Installa le dipendenze (npm install) e segui l'output. Se non va a buon fine:
- Controlla che
package.jsonsia nella radice dell'applicazione (non in una sottocartella). - Per Next.js: verifica che
nextsia independenciese non indevDependencies(l'installazione di produzione salta le dipendenze di sviluppo). - Per Nuxt: anche
nuxtdeve essere una dipendenza normale.
Aggiungi le variabili d'ambiente
Nell'app vai in Impostazioni → Variabili d'ambiente → Aggiungi una variabile. La modalità Produzione imposta già NODE_ENV=production.
Per le app Next.js che leggono valori in fase di esecuzione (URL del database, chiavi API), aggiungili qui. Non caricare un file .env con dati segreti: il posto giusto sono le variabili d'ambiente dell'app.
Salvando le impostazioni l'app si riavvia, quindi le nuove variabili si applicano subito.
Passo 5: verifica
Apri l'URL della tua applicazione. Dovresti vedere la tua app.
Se vedi una pagina di errore di Passenger, aprila e guarda in fondo: quasi sempre c'è uno stack trace chiaro. I due casi più comuni:
Error: Cannot find module 'next': npm install non è stato eseguito, oppure è stato eseguito nella cartella sbagliata. Clicca di nuovo Installa le dipendenze (npm install).
Error: ENOENT: no such file or directory, open '.next/...': hai caricato il sorgente ma non la cartella compilata .next/. Fai la build in locale e ricarica.
Come pubblicare gli aggiornamenti
Ripeti i passi 1 e 2 e clicca Riavvia sull'app. Nel dettaglio:
1. Build in locale npm run build
2. Caricamento .next/ o .output/, più sorgenti/configurazioni modificate
3. Pannello Riavvia l'appSe modifichi package.json, clicca Installa le dipendenze (npm install) prima di riavviare. Preferisci la riga di comando? In Sito web → Terminale la scheda dell'app mostra il comando per entrare nel suo ambiente.
Intoppi comuni
WebSocket: Passenger gestisce HTTP/1.1 e HTTP/2. L'upgrade a WebSocket funziona per le route integrate di Next.js e Nuxt. Se usi un server WebSocket separato (ws, socket.io), condivide la stessa porta e si avvia dallo stesso server.cjs: nessuna configurazione in più.
Caricamento di file / limiti body-parser in next.config.js: il limite predefinito di Passenger per il corpo di una richiesta è 10 MB. Se carichi file grandi, alza passenger_max_request_size con un .htaccess in public_html:
PassengerMaxRequestSize 52428800(50 MB in byte.)
Cron job: se l'app ha bisogno di attività in background (invio di newsletter, esportazioni programmate), non eseguirle dentro il processo web. Usa Sito web → Cron job per lanciare direttamente uno script Node:
/home/<account>/nodevenv/myapp/20/bin/node /home/<account>/myapp/scripts/send-newsletter.jsMemoria del processo: Passenger riavvia l'app se supera il limite di RAM dell'account (dipende dal piano). Una tipica app Next.js / Nuxt a riposo usa meno di 100 MB. Se raggiungi i limiti, analizza con process.memoryUsage() e cerca eventuali perdite di memoria prima di pensare di aver bisogno di un piano più grande.
Domini personalizzati e HTTPS: l'indirizzo che imposti per l'app è quello su cui Passenger si mette in ascolto. L'SSL è automatico, senza configurazioni in più. Per un altro dominio o un sottodominio, aggiungilo prima in Sito web → Domini, poi sceglilo come indirizzo dell'app.
Versione di Node: l'elenco Versione mostra tutte le versioni installate; puoi cambiarla nelle Impostazioni dell'app.
Quando non usare l'hosting condiviso per Node
Diciamolo chiaramente: Node.js sull'hosting condiviso funziona benissimo per portfolio, blog, pagine di marketing, piccoli front-end SaaS, strumenti interni. Fa fatica con:
- API ad alto volume (>50 richieste/sec in modo continuativo): sentirai il limite di CPU dell'account
- App con molti WebSocket e migliaia di connessioni contemporanee
- App che avviano processi worker (worker di code, scraper): il budget di processi per account di Passenger lo rende scomodo
- Tutto ciò che richiede systemd, Docker o accesso root
Per questi casi la scelta giusta è il nostro VPS: root completo, il tuo kernel, ci fai girare quello che vuoi. Ma per la maggior parte delle app Next.js e Nuxt senza traffico enorme, questa guida è tutto ciò che ti serve.
In breve
npm run buildin locale- Carica
.next/(Next) o.output/(Nuxt) +package.json+server.cjs - Sito web → Node.js e Python → Applicazione Node.js → la cartella, file di avvio
server.cjs, modalità Produzione - Installa le dipendenze (npm install), poi Riavvia
Se qualcosa non funziona, apri un ticket: incolla la pagina di errore di Passenger e ti indichiamo la riga.
— Il team Rivervo