Aplicações Node.js, Next.js e Nuxt.
Como os projetos Node.js são detectados e iniciados: versão do Node, gerenciador de pacotes, Next.js e Nuxt (servidor ou estático), SvelteKit, Astro, Express e companhia, a variável PORT e as migrations do Prisma.
Um repositório com package.json é um projeto Node.js. Nós escolhemos o framework, o gerenciador de pacotes e a versão do Node, fazemos o build e iniciamos a aplicação — você só faz o push.
Versão do Node e gerenciador de pacotes
- Node.js — vem de
engines.nodenopackage.jsonou do.nvmrc: a mais nova entre 24, 22, 20, 18 e 16 que atenda. Sem nenhum dos dois, Node.js 22. - Gerenciador de pacotes — pelo arquivo de lock:
pnpm-lock.yaml→ pnpm,yarn.lock→ yarn, senão npm (npm ciquando existe umpackage-lock.json). - Build — o script
build, quando opackage.jsontem um.
Frameworks
| Framework | Como roda |
|---|---|
| Next.js | como servidor (next start) — renderização no servidor, rotas de API e middleware funcionam normalmente |
Next.js com output: 'export' | como site estático a partir de out |
| Nuxt | como servidor (.output/server/index.mjs) |
Nuxt com ssr: false e um script generate | como site estático a partir de .output/public |
| SvelteKit | como servidor com adapter-node; com adapter-static, como site estático |
| Astro | como site estático; com @astrojs/node, como servidor |
| NestJS | dist/main.js depois do build |
| Express, Fastify, Koa, Hono e outros servidores | o arquivo em scripts.start (node server.js), senão main, senão server.js, app.js, index.js ou main.js |
Projetos só de front-end — Vite, Create React App, Angular, Vue CLI e outros — são servidos como sites estáticos; veja Sites estáticos.
Escute na PORT
Um servidor precisa escutar na porta da variável PORT, em todas as interfaces:
const port = process.env.PORT || 3000
app.listen(port, '0.0.0.0')O Next.js e o Nuxt já fazem isso sozinhos. Se a sua aplicação escuta numa porta fixa, ela não recebe visitantes — o deploy para na verificação de início e a versão anterior continua rodando.
Valores na hora do build
As variáveis da aba Variáveis chegam à aplicação em execução, não ao build. Valores que o build grava no código do cliente — como NEXT_PUBLIC_… no Next.js ou VITE_… — são lidos do seu repositório, por exemplo de um arquivo .env.production versionado. O código do lado do servidor lê a aba Variáveis normalmente.
Seu próprio comando de início
Se o início detectado não for o que você quer, defina Configurações → Configurações de build → Comando de início, por exemplo node dist/server.js ou npm run start:prod. Os comandos de instalação e de build também podem ser alterados ali.
Bancos de dados e Prisma
Adicione PostgreSQL ou MySQL ao projeto e leia DATABASE_URL — ela é definida para você. Com o Prisma nas dependências, o comando de release recomendado é npx prisma migrate deploy: ele roda em cada deploy, antes de a nova versão receber visitantes. Veja Deploys.
Para filas com BullMQ, adicione Valkey e use REDIS_URL. Rode o worker da fila como worker em segundo plano — na aba Processos ou como um serviço separado, com recursos próprios. Veja Serviços de um projeto.
Arquivos que sobrevivem a um deploy
Cada deploy começa de uma cópia nova do seu repositório. Os arquivos que a aplicação grava em /data são mantidos entre deploys e têm backup diário; o que for gravado em outro lugar some no deploy seguinte. Para uploads e mídia, o armazenamento de objetos costuma ser a melhor escolha.
Monorepos
Num repositório com vários projetos, defina a Pasta do projeto ao criar a aplicação (por exemplo, apps/web). Outra pasta do mesmo repositório pode rodar como um serviço web separado — veja Serviços de um projeto.