Custom Server

Core Idea

Ejete do servidor integrado do next start só quando o router do Next.js não atende os requisitos; a maioria dos apps não precisa disso, e um backend existente já pode conviver com Next.js sem virar "custom server".

Key Concepts

• next({dev, dir, conf, ...}): função que inicializa a app Next.js dentro do custom server, retorna app com app.getRequestHandler().
• app.prepare(): precisa resolver antes de o servidor HTTP começar a atender requests.
• Incompatível com output: 'standalone': standalone gera um server.js mínimo próprio; standalone não traceia arquivos de custom server, os dois modos não se combinam.
• server.js não passa pelo Next.js Compiler: sintaxe e imports precisam ser compatíveis diretamente com a versão do Node em uso.

Code Examples

import { createServer } from 'http'
import next from 'next'

const port = parseInt(process.env.PORT || '3000', 10)
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  createServer((req, res) => {
    handle(req, res)
  }).listen(port)
})

• O que demonstra: setup mínimo de custom server com http.createServer delegando pro request handler do Next.js.

{
  "scripts": {
    "dev": "node server.js",
    "build": "next build",
    "start": "NODE_ENV=production node server.js"
  }
}

• O que demonstra: scripts substituem next dev/next start pelo entrypoint próprio.

Reference Tables

Option	Type	Description
conf	Object	Mesmo objeto de next.config.js. Default {}
dev	Boolean	Opcional. Modo dev. Default false
dir	String	Opcional. Localização do projeto. Default '.'
quiet	Boolean	Opcional. Oculta mensagens de erro com info do servidor. Default false
hostname	String	Opcional. Hostname atrás do qual o servidor roda
port	Number	Opcional. Porta atrás da qual o servidor roda
httpServer	node:http#Server	Opcional. HTTP Server por trás do Next.js
turbopack	Boolean	Opcional. Habilita Turbopack (default habilitado)
webpack	Boolean	Opcional. Habilita webpack

Anti-patterns

• Combinar custom server com output: 'standalone': standalone ignora o custom server e gera seu próprio server.js; os dois não funcionam juntos.
• Criar custom server só para ter um backend junto: um backend existente ao lado do Next.js não exige custom server; isso só é necessário quando o router integrado não atende o requisito.

Key Takeaways

1. Use custom server apenas quando o router integrado do Next.js não cobre o caso de uso, não por padrão.
2. app.prepare() deve resolver (.then()) antes de o servidor começar a escutar.
3. server.js roda fora do pipeline do Next.js Compiler; sintaxe precisa ser compatível com o Node.js em uso diretamente.
4. turbopack/webpack como opções do next() controlam o bundler mesmo em modo custom server.

Connects To

• output: standalone (next.config): modo mutuamente exclusivo com custom server.
• next dev / next start: comportamento padrão que o custom server substitui.