Publique a sua aplicação Node.js no alojamento Rivervo (Next.js e Nuxt).
Muita gente pensa que as aplicações Node.js têm de estar num VPS. Não é assim — todos os planos de alojamento partilhado Rivervo têm Node.js e Python no menu do site, que arranca um processo Phusion Passenger para a sua aplicação por trás do mesmo front-end Apache que serve os seus outros sites.
Este guia percorre todo o processo para as duas frameworks mais comuns: Next.js e Nuxt 3. O resultado final: a sua aplicação em https://oseudominio.pt (ou em qualquer subdomínio), a correr num processo Node.js real, a sobreviver a reinícios e a reiniciar com um clique.
Se nunca publicou uma aplicação Node num alojamento partilhado, a parte em que todos ficam presos é o ficheiro de arranque — o Passenger precisa de um único script de entrada que arranque a sua framework. Deixamos abaixo um para cada framework; basta copiar e colar, sem alterações.
O que precisa antes de começar
- Um plano de alojamento Rivervo (qualquer um — as aplicações Node.js funcionam em todos os planos)
- Node.js v20 ou mais recente no seu computador para compilar a aplicação
- O resultado da compilação, pronto a carregar (explicamos para cada framework)
- Acesso ao Gestor de ficheiros ou por SFTP à sua conta (ambos servem)
Não precisa de root, sudo, systemd nem de configuração de proxy inverso. O Passenger trata de tudo isso.
Passo 1 — Compile a aplicação localmente
Vai carregar uma aplicação compilada, não o código-fonte. O painel instala as dependências, mas não compila React nem executa uma compilação Vite. Faça isso primeiro no seu computador.
Next.js:
npm ci
npm run buildIsto gera .next/ (o resultado da compilação). Não execute next start aqui — vamos arrancá-la a partir do ficheiro de arranque daqui a pouco.
Nuxt 3:
npm ci
npm run buildIsto gera .output/ (o diretório de compilação universal do Nuxt). O mesmo princípio — não execute nada ainda.
Passo 2 — Carregue os ficheiros certos
Não precisa de carregar node_modules/. O painel instala as dependências por si. Também não precisa do git nem das caches de compilação.
Carregue para a sua conta, de preferência para um caminho fora de public_html (por exemplo, /home/<conta>/myapp/). Porquê fora? Porque o Passenger monta automaticamente o public_html na raiz do URL, e colocar lá o código da aplicação deixa-o exposto.
| Framework | Carregue | Ignore |
|---|---|---|
| Next.js | .next/, public/, package.json, package-lock.json, next.config.js, o seu server.cjs (abaixo) | node_modules/, .git/, .env.local |
| Nuxt 3 | .output/, package.json, package-lock.json, o seu server.cjs (abaixo) | node_modules/, .nuxt/, .git/, código-fonte pages/, components/ |
Há duas formas de colocar lá os ficheiros:
- Site → Ficheiros → carregar um zip → extraí-lo é o mais fácil se a sua ligação for instável.
- SFTP (FileZilla, Cyberduck,
rsync) é mais rápido para publicações repetidas. O servidor, a porta, o utilizador e a palavra-passe estão em Site → SSH e SFTP.
Passo 3 — Adicione o ficheiro de arranque
É o ficheiro que o Passenger executa quando chega um pedido. Coloque-o ao lado do package.json, na pasta da aplicação.
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}`)
})
})O que faz:
- Carrega o Next e aponta-o para o diretório atual (onde estão o
.next/e opackage.json). - Cria um gestor de pedidos a partir do router interno do Next.
- Inicia um servidor HTTP na porta que o Passenger atribui (
process.env.PORT). - Recorre à porta
3000para testes locais.
O dev é obtido automaticamente de NODE_ENV — defina o modo Produção no painel (fazemos isso no Passo 4) e o Next corre em modo de produção.
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}`)
})
})
})O que faz:
- Importa dinamicamente o
.output/server/index.mjsdo Nuxt (a entrada gerada pornpm run build). - Usa
createApp()para criar a instância do servidor H3. - Fica à escuta na porta atribuída pelo Passenger.
O import() dinâmico é intencional — os módulos .mjs não podem ser carregados com require(), mas um ficheiro .cjs pode importá-los dinamicamente. É o padrão mais limpo que funciona dentro do lançador do Passenger.
Passo 4 — Crie a aplicação no painel
Abra o seu projeto → Site → Node.js e Python → Aplicação Node.js.
| Campo | Valor |
|---|---|
| Versão | 20 ou mais recente |
| Modo | Produção |
| Pasta | myapp na sua pasta pessoal (onde carregou os ficheiros) |
| Endereço | oseudominio.pt (ou um subdomínio como app.oseudominio.pt) |
| Ficheiro de arranque | server.cjs |
Clique em Criar. É criado um ambiente Node.js em ~/nodevenv/myapp/20/.
Instalar as dependências
Depois de criada a aplicação, clique em Instalar dependências (npm install) e acompanhe o resultado. Se falhar:
- Confirme que o
package.jsonestá na raiz da aplicação (e não numa subpasta). - No Next.js: confirme que
nextestá emdependenciese não emdevDependencies(a instalação de produção ignora as dependências de desenvolvimento). - No Nuxt: o próprio
nuxttambém deve ser uma dependência normal.
Adicionar variáveis de ambiente
Nas Definições da aplicação → Variáveis de ambiente → Adicionar uma variável. O modo Produção já define NODE_ENV=production.
Nas aplicações Next.js que leem valores em tempo de execução (URLs de bases de dados, chaves de API), adicione-os aqui. Não publique um ficheiro .env com segredos — as variáveis de ambiente da aplicação são o sítio certo.
Guardar as definições reinicia a aplicação, por isso as novas variáveis aplicam-se de imediato.
Passo 5 — Verifique
Abra o URL da aplicação. Deve ver a sua aplicação.
Se aparecer uma página de erro do Passenger, expanda-a e veja o fundo — quase sempre há um rastreio de pilha claro. Os dois mais comuns:
Error: Cannot find module 'next' — o npm install não correu, ou correu na pasta errada. Clique de novo em Instalar dependências (npm install).
Error: ENOENT: no such file or directory, open '.next/...' — carregou o código-fonte, mas não o diretório compilado .next/. Compile localmente e volte a carregar.
Como publicar atualizações
Repita os passos 1 e 2 e clique em Reiniciar na aplicação. Em concreto:
1. Compilar localmente npm run build
2. Carregar .next/ ou .output/, mais o código/configuração alterados
3. Painel Reiniciar a aplicaçãoSe alterar o package.json, clique em Instalar dependências (npm install) antes de reiniciar. Prefere a linha de comandos? Em Site → Terminal, o cartão da aplicação mostra o comando para entrar no ambiente dela.
Problemas comuns
WebSockets: o Passenger suporta HTTP/1.1 e HTTP/2. O upgrade para WebSocket funciona com as rotas integradas do Next.js e do Nuxt. Se usar um servidor WebSocket separado (ws, socket.io), este partilha a mesma porta e arranca a partir do mesmo server.cjs — sem configuração extra.
Carregamento de ficheiros / limites do body-parser no next.config.js: o limite predefinido do corpo dos pedidos no Passenger é de 10 MB. Se carregar ficheiros grandes, aumente o passenger_max_request_size através do .htaccess em public_html:
PassengerMaxRequestSize 52428800(50 MB em bytes.)
Tarefas cron: se a sua aplicação precisa de tarefas em segundo plano (envio de newsletters, exportações agendadas), não as execute dentro do processo web. Use Site → Tarefas cron para chamar diretamente um script Node:
/home/<conta>/nodevenv/myapp/20/bin/node /home/<conta>/myapp/scripts/send-newsletter.jsMemória do processo: o Passenger reinicia a aplicação se ultrapassar o limite de RAM por conta (depende do plano). Numa aplicação Next.js / Nuxt típica, em repouso fica abaixo dos 100 MB. Se estiver a atingir limites, analise com process.memoryUsage() e procure fugas de memória antes de concluir que precisa de um plano maior.
Domínios próprios e HTTPS: o endereço que define para a aplicação é o que o Passenger associa. O SSL é automático — sem configuração extra. Para outro domínio ou um subdomínio, adicione-o primeiro em Site → Domínios e depois escolha-o como endereço da aplicação.
Versão do Node: a lista Versão mostra todas as versões instaladas; mude-a nas Definições da aplicação.
Quando não usar alojamento partilhado para Node
Sendo diretos — o Node.js em alojamento partilhado funciona muito bem para portefólios, blogs, páginas de marketing, front-ends de pequenos SaaS e ferramentas internas. Tem dificuldades com:
- APIs de alto débito (>50 pedidos/s de forma contínua) — vai sentir o limite de CPU por conta
- Aplicações com muito WebSocket e milhares de ligações em simultâneo
- Aplicações que lançam processos de trabalho (workers de filas, scrapers) — o limite de processos por conta do Passenger torna isto complicado
- Tudo o que precise de systemd, Docker ou acesso root
Para esses casos, o nosso VPS é a escolha certa — root completo, o seu próprio kernel, corre o que quiser. Mas para a maioria das aplicações Next.js e Nuxt sem tráfego enorme, este guia é tudo o que precisa.
Em resumo
npm run buildlocalmente- Carregue
.next/(Next) ou.output/(Nuxt) +package.json+server.cjs - Site → Node.js e Python → Aplicação Node.js → a pasta, ficheiro de arranque
server.cjs, modo Produção - Instalar dependências (npm install) e depois Reiniciar
Se algo correr mal, abra um pedido de suporte — cole a página de erro do Passenger e indicamos-lhe a linha.
— Equipa Rivervo