Começar

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.

3 MIN DE LEITURA

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.node no package.json ou 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 ci quando existe um package-lock.json).
  • Build — o script build, quando o package.json tem um.

Frameworks

FrameworkComo roda
Next.jscomo 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
Nuxtcomo servidor (.output/server/index.mjs)
Nuxt com ssr: false e um script generatecomo site estático a partir de .output/public
SvelteKitcomo servidor com adapter-node; com adapter-static, como site estático
Astrocomo site estático; com @astrojs/node, como servidor
NestJSdist/main.js depois do build
Express, Fastify, Koa, Hono e outros servidoreso 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.

Ainda com dúvidas?

Fale com a gente no chat — a AI responde na hora e um engenheiro entra quando é preciso, a qualquer hora do dia.

Falar com o suporte