Publique seu aplicativo Node.js na hospedagem da Rivervo (Next.js e Nuxt).
Muita gente acha que aplicativos Node.js precisam ficar em um VPS. Não precisam: todo plano de hospedagem compartilhada da Rivervo tem Node.js e Python no menu do site, que inicia um processo do Phusion Passenger para o seu aplicativo atrás do mesmo Apache que atende seus outros sites.
Este guia mostra o fluxo completo para os dois frameworks mais usados: Next.js e Nuxt 3. O resultado final: seu aplicativo em https://seudominio.com.br (ou em qualquer subdomínio), rodando em um processo Node.js de verdade, resistindo a reinicializações e reiniciável com um clique.
Se você nunca publicou um aplicativo Node em hospedagem compartilhada, a parte em que todo mundo trava é o arquivo de inicialização: o Passenger precisa de um único script de entrada que inicie o seu framework. Abaixo damos um para cada framework; é só copiar e colar, sem nenhuma edição.
O que você precisa antes de começar
- Um plano de hospedagem da Rivervo (qualquer um: aplicativos Node.js funcionam em todos os planos)
- Node.js v20 ou mais recente no seu computador para gerar o build do aplicativo
- O build pronto para enviar (explicamos para cada framework)
- Acesso ao gerenciador de arquivos ou SFTP da sua conta (os dois funcionam)
Você não precisa de root, sudo, systemd nem configuração de proxy reverso. O Passenger cuida de tudo isso.
Passo 1: gere o build do aplicativo no seu computador
Você vai enviar o aplicativo já compilado, não o código-fonte. O painel instala as dependências, mas não compila React nem roda um build do Vite. Faça isso antes no seu computador.
Next.js:
npm ci
npm run buildIsso gera o .next/ (o resultado do build). Não rode next start aqui: vamos iniciá-lo pelo arquivo de inicialização daqui a pouco.
Nuxt 3:
npm ci
npm run buildIsso gera o .output/ (o diretório de build universal do Nuxt). Mesma coisa: não rode nada ainda.
Passo 2: envie os arquivos certos
Não é preciso enviar o node_modules/. O painel instala as dependências para você. Também não são necessários o git nem caches de build.
Envie para a sua conta, de preferência para um caminho fora do public_html (por exemplo, /home/<account>/myapp/). Por que fora? Porque o Passenger monta o public_html na raiz do URL automaticamente, e colocar o código do aplicativo ali deixa esse código exposto.
| Framework | Envie estes | Não envie |
|---|---|---|
| Next.js | .next/, public/, package.json, package-lock.json, next.config.js, seu server.cjs (abaixo) | node_modules/, .git/, .env.local |
| Nuxt 3 | .output/, package.json, package-lock.json, seu server.cjs (abaixo) | node_modules/, .nuxt/, .git/, os fontes pages/, components/ |
Duas formas de levar os arquivos até lá:
- Site → Arquivos → enviar um zip → extrair é a mais fácil se a sua conexão for instável.
- SFTP (FileZilla, Cyberduck,
rsync) é mais rápido para deploys repetidos. Servidor, porta, usuário e senha estão em Site → SSH e SFTP.
Passo 3: adicione o arquivo de inicialização
Este é o arquivo que o Passenger executa quando chega uma requisição. Coloque-o ao lado do package.json na pasta do aplicativo.
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 ele faz:
- Carrega o Next e aponta para o diretório atual (onde ficam o
.next/e opackage.json). - Cria um manipulador de requisições a partir do roteador interno do Next.
- Inicia um servidor HTTP na porta definida pelo Passenger (
process.env.PORT). - Usa a porta
3000como alternativa para testes locais.
O dev é definido automaticamente a partir do NODE_ENV: escolha o modo Produção no painel (faremos isso no Passo 4) e o Next roda 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 ele faz:
- Importa dinamicamente o
.output/server/index.mjsdo Nuxt (a entrada gerada pelonpm run build). - Usa
createApp()para criar a instância do servidor H3. - Escuta na porta definida pelo Passenger.
O import() dinâmico é proposital: módulos .mjs não podem ser carregados com require(), mas um arquivo .cjs pode importá-los dinamicamente. É o padrão mais limpo que funciona dentro do inicializador do Passenger.
Passo 4: crie o aplicativo no painel
Abra seu projeto → Site → Node.js e Python → Aplicativo Node.js.
| Campo | Valor |
|---|---|
| Versão | 20 ou mais recente |
| Modo | Produção |
| Pasta | myapp na sua pasta pessoal (onde você enviou os arquivos) |
| Endereço | seudominio.com.br (ou um subdomínio como app.seudominio.com.br) |
| Arquivo de inicialização | server.cjs |
Clique em Criar. Um ambiente Node.js é criado em ~/nodevenv/myapp/20/.
Instale as dependências
Depois de criar o aplicativo, clique em Instalar dependências (npm install) nele e acompanhe a saída. Se falhar:
- Confira se o
package.jsonestá na raiz do aplicativo (e não em uma subpasta). - Para Next.js: confirme que o
nextestá emdependencies, não emdevDependencies(a instalação de produção ignora as dependências de desenvolvimento). - Para Nuxt: o próprio
nuxttambém deve ser uma dependência normal.
Adicione variáveis de ambiente
Nas Configurações do aplicativo → Variáveis de ambiente → Adicionar variável. O modo Produção já define NODE_ENV=production.
Para aplicativos Next.js que leem valores em tempo de execução (URLs de banco de dados, chaves de API), adicione-os aqui. Não envie um arquivo .env com segredos: o lugar certo são as variáveis de ambiente do aplicativo.
Salvar as configurações reinicia o aplicativo, então as novas variáveis passam a valer na hora.
Passo 5: confira
Acesse o URL do aplicativo. Você deve ver o seu aplicativo.
Se aparecer uma página de erro do Passenger, expanda-a e olhe no final: quase sempre há um stack trace claro. Os dois mais comuns:
Error: Cannot find module 'next': o npm install não rodou, ou rodou na pasta errada. Clique de novo em Instalar dependências (npm install).
Error: ENOENT: no such file or directory, open '.next/...': você enviou o código-fonte, mas não o diretório .next/ compilado. Gere o build no seu computador e envie de novo.
Como publicar atualizações
Repita os passos 1 e 2 e clique em Reiniciar no aplicativo. Na prática:
1. Build locally npm run build
2. Upload .next/ or .output/, plus any changed source/config
3. Panel Restart the appSe você alterar o package.json, clique em Instalar dependências (npm install) antes de reiniciar. Prefere a linha de comando? Em Site → Terminal, o cartão do aplicativo mostra o comando para entrar no ambiente dele.
Armadilhas comuns
WebSockets: o Passenger trabalha com HTTP/1.1 e HTTP/2. O upgrade para WebSocket funciona nas rotas nativas do Next.js e do Nuxt. Se você usa um servidor WebSocket separado (ws, socket.io), ele compartilha a mesma porta e inicia pelo mesmo server.cjs, sem configuração extra.
Upload de arquivos / limites de body-parser no next.config.js: o limite padrão do corpo da requisição no Passenger é de 10 MB. Se você envia arquivos grandes, aumente o passenger_max_request_size pelo .htaccess no public_html:
PassengerMaxRequestSize 52428800(50 MB em bytes.)
Tarefas cron: se o seu aplicativo precisa de tarefas em segundo plano (envio de newsletters, exportações agendadas), não as rode dentro do processo web. Use Site → Tarefas cron para chamar um script Node diretamente:
/home/<account>/nodevenv/myapp/20/bin/node /home/<account>/myapp/scripts/send-newsletter.jsMemória do processo: o Passenger reinicia o aplicativo se ele passar do limite de RAM da conta (que depende do seu plano). Um aplicativo Next.js / Nuxt típico fica abaixo de 100 MB em repouso. Se estiver batendo no limite, analise com process.memoryUsage() e procure vazamentos antes de concluir que precisa de um plano maior.
Domínios próprios e HTTPS: o endereço que você define para o aplicativo é o que o Passenger vincula. O SSL é automático, sem configuração extra. Para outro domínio ou subdomínio, adicione-o antes em Site → Domínios e depois escolha-o como endereço do aplicativo.
Versão do Node: a lista Versão mostra todas as versões instaladas; troque nas Configurações do aplicativo.
Quando não usar hospedagem compartilhada para Node
Sendo direto: Node.js em hospedagem compartilhada funciona muito bem para portfólios, blogs, páginas de marketing, front-ends de pequenos SaaS e ferramentas internas. Ele sofre com:
- APIs de alto volume (>50 req/s de forma contínua): você vai sentir o limite de CPU da conta
- Aplicativos com uso intenso de WebSocket e milhares de conexões simultâneas
- Aplicativos que criam processos de trabalho (workers de fila, scrapers): o limite de processos por conta do Passenger complica isso
- Qualquer coisa que precise de systemd, Docker ou acesso root
Para esses casos, o nosso VPS é o caminho certo: root completo, kernel próprio, roda o que você quiser. Mas para a maioria dos aplicativos Next.js e Nuxt que não recebem um tráfego enorme, este guia é tudo de que você precisa.
Resumo
npm run buildno seu computador- Envie
.next/(Next) ou.output/(Nuxt) +package.json+server.cjs - Site → Node.js e Python → Aplicativo Node.js → a pasta, arquivo de inicialização
server.cjs, modo Produção - Instalar dependências (npm install) e depois Reiniciar
Se algo não funcionar, abra um chamado: cole a página de erro do Passenger e mostramos a linha do problema.
— Equipe Rivervo