A resposta curta

Para fazer deploy de uma app Next.js como servidor, use next build e depois next start. Não use next dev. Trate NEXT_PUBLIC_ como público e fixo nesse build. Confira a memória do build e o que as réplicas não compartilham antes de escalar.

A receita Next.js na Unbroker exige Pro, com memória suficiente para o build e para o servidor em execução. O guia não publica um número para essa memória. Os passos estão em deploy de Next.js e em Deploy a Next.js application.

Servidor ou export estático

Escolha o preset Next.js quando o app precisa de um servidor. Um export estático é outra forma. O Next.js liga isso com output: 'export' em next.config.js. next build grava então uma pasta out de HTML, CSS e JavaScript.

Esse export não oferece recursos que precisam de um servidor no request. O Next.js lista cookies, server actions, regeneração estática incremental, redirects e route handlers que leem o request entre o que não é suportado. Um route handler num export pode emitir um GET estático só se você marcar dynamic = 'force-static'. A fonte é Next.js static exports.

O guia da Unbroker diz o mesmo corte: um export estático produz arquivos e não pode oferecer recursos de servidor no request. Este texto não descreve uma receita Free separada para um export de Next.js. O Free inclui HTML estático e sites estáticos de React, Vue, Vite e Astro, mais Node.js gerenciado. Outras receitas de framework, inclusive a de Next.js, são Pro. O preset do Astro serve os arquivos gerados, e um adaptador de servidor é outro deploy. Essa decisão está em hospedagem Astro.

Os scripts que importam

Os scripts de produção do guia são:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start --hostname 0.0.0.0"
  }
}

next build cria o build de produção. next start executa esse build. next dev é o servidor de desenvolvimento. Um next sem comando é um alias de next dev, então não é um início de produção. A referência é a CLI do Next.js.

next start lê PORT. A porta padrão da CLI é 3000, e -p ou --port substituem esse valor. O Next.js diz que PORT não pode ficar em .env, porque o servidor HTTP sobe antes de esse arquivo ser lido. Uma variável de plataforma chamada PORT não é esse arquivo.

A CLI lista --hostname com padrão 0.0.0.0 para next start. O script de exemplo da Unbroker passa a flag mesmo assim. Se você usa standalone output ou um servidor próprio, ajuste o comando de início a essa saída. O guia não nomeia um comando substituto.

Rode o install com lockfile, o build e o start localmente. Teste uma rota dinâmica além da home.

Variáveis públicas de build e segredos de runtime

NEXT_PUBLIC_ é para o código do navegador. Trate como público. A Unbroker escolhe as variáveis públicas de build, inclusive NEXT_PUBLIC_* e VITE_*, para o ambiente de destino antes do build. Uma mudança que já está no frontend pede um build novo. Como os escopos funcionam está em Variáveis de ambiente e segredos.

Variáveis privadas ficam só em runtime, exceto as credenciais de registro de pacotes que a documentação nomeia. Não faça a geração estática depender de um segredo de produção que falta durante o build. Mova esse trabalho para o request, ou use um processo de build feito para isso.

As variáveis são All, Production ou Preview. Um preview novo copia All e Preview, não valores que são só de Production. Faça um novo deploy depois de uma mudança de runtime para a revisão em execução pegar o valor.

Quando o build fica sem memória

Veja onde o build falhou: instalação de dependências, compilação ou geração de páginas. Reduza trabalho que o build não precisa, ou mude a capacidade dessa etapa. Réplicas extras de runtime não consertam um build que já ficou sem memória.

A documentação não publica um limite de memória para essa falha. A receita ainda pede memória suficiente para o build e para o runtime. Se o processo já está rodando e depois falha, é outra etapa. Como ler o log certo está em Depurar um deploy que falhou.

Mais de uma réplica

Réplicas não compartilham a memória do processo nem arquivos locais. Revise sessões, caches, arquivos enviados e estado gerado antes de somar uma réplica. Coloque dados que precisam coincidir num banco ou em outro armazenamento compartilhado.

Um serviço com volume persistente fica em uma réplica. O volume pode crescer até 50 GB e não pode encolher. Apagar o serviço apaga o volume. Esse limite está em volumes persistentes. Como a quantidade de réplicas muda está em Autoscaling de réplicas. Serviços Free rodam uma réplica. Réplicas configuráveis são Pro.

Confira mais do que a home

Abra a URL que o Cloud entrega. Confira uma página renderizada no servidor, uma rota de API se houver, callbacks de autenticação e assets estáticos. Atualize as allowlists de callback com a origem publicada. Uma home que renderiza não exercita o app inteiro.

Um domínio próprio é outro passo, diferente da primeira URL. O DNS e o certificado estão em Domínio próprio e HTTPS. Qual push produziu a revisão está em Deploy com git push.

Como isso funciona na Unbroker

Crie um serviço de repositório, selecione Next.js e revise o branch, o comando de build e o comando de start. Carregue as variáveis públicas antes do build. Adicione credenciais privadas em Variables.

A receita Next.js exige Pro. O Pro custa $25 por mês com $25 de crédito de uso. O crédito não acumula. Se o uso fica abaixo do crédito, a cobrança continua $25. O cluster, o volume e o build ficam fora dessa mensalidade. As linhas estão em preços e em Plans.

Um frontend e uma API no mesmo projeto estão em frontend e API. Um app que começou em outra ferramenta e ainda aponta para o banco dessa ferramenta está em um app feito com IA em produção.

Checklist

  1. Deixe build em next build e start em next start, não em next dev.
  2. Passe --hostname 0.0.0.0 como o script do guia, mesmo que o padrão atual da CLI seja o mesmo host.
  3. Deixe a plataforma entregar PORT. Não dependa de PORT dentro de .env.
  4. Carregue os valores NEXT_PUBLIC_ antes do build e reconstrua quando eles mudarem.
  5. Deixe segredos de produção fora da geração estática.
  6. Se o build ficar sem memória, nomeie a etapa antes de somar réplicas de runtime.
  7. Antes de uma segunda réplica, mova sessões, caches e uploads para um armazenamento compartilhado. Um volume deixa o serviço em uma réplica.
  8. Peça uma página de servidor, uma rota de API e um callback de auth na origem publicada.
  9. Use o Pro para a receita Next.js. Não trate a receita Node.js do Free como este preset.

Perguntas frequentes

Devo usar next dev em produção?

Não. next dev é o servidor de desenvolvimento, com recarga automática. O caminho de produção é next build e depois next start. A CLI do Next.js trata um next sem comando como alias de next dev. O guia de Next.js da Unbroker diz para não usar next dev como comando de início em produção.

Por que uma variável NEXT_PUBLIC_ não muda depois que eu edito?

Valores NEXT_PUBLIC_ são para o código do navegador. A Unbroker escolhe as variáveis públicas de build, inclusive NEXT_PUBLIC_ e VITE_, para o ambiente de destino antes do build e as embute no frontend. Mudar uma exige um build novo. O restante fica só em runtime, exceto credenciais de registro de pacotes.

Dá para usar um segredo durante o next build?

Não faça a geração estática depender de um segredo de produção que não está disponível durante o build. A Unbroker mantém variáveis privadas só em runtime. Mova esse trabalho para o request, ou use um processo de build feito para isso. Um valor com o prefixo NEXT_PUBLIC_ é público mesmo se você o digitou em Variables.

Por que o build do Next.js fica sem memória?

Veja em qual etapa falhou: instalação de dependências, compilação ou geração de páginas. Reduza trabalho de build que não é necessário, ou ajuste a capacidade dessa etapa. Réplicas extras de runtime não consertam um build que ficou sem memória. A documentação não publica um número de memória para essa falha.

Dá para rodar Next.js em mais de uma réplica?

Réplicas não compartilham a memória do processo nem arquivos locais. Revise sessões, caches, arquivos enviados e estado gerado antes de escalar, e coloque o estado compartilhado num banco ou em outro armazenamento comum. Um serviço com volume persistente fica em uma réplica. A quantidade de réplicas é configurável no Pro. Serviços Free rodam uma.

Preciso de um servidor ou posso exportar arquivos estáticos?

Um servidor Next.js em execução é o preset quando o app precisa de trabalho no request. output: 'export' grava uma pasta out de HTML, CSS e JavaScript. O Next.js não suporta cookies, server actions, regeneração estática incremental nem route handlers que leem o request nesse export. A Unbroker trata o export estático como outra forma, diferente da receita de servidor.

Em qual porta o next start escuta?

O padrão da CLI do Next.js é a porta 3000. next start lê a variável PORT, e -p ou --port substituem esse valor. O Next.js diz que PORT não pode ser definido num arquivo .env, porque o servidor HTTP sobe antes de esse arquivo ser lido. A flag de hostname tem padrão 0.0.0.0. O script de exemplo da Unbroker mesmo assim passa --hostname 0.0.0.0.