Custom Server

Core Idea

Next.js já roda seu próprio servidor com next start; um custom server (via createServer + next({dev})) só é necessário pra padrões que o roteador integrado não atende, é uma escotilha de ejeção, não o caminho recomendado.

Key Concepts

next({ dev }) + app.getRequestHandler(): cria a instância Next.js e obtém o handler que processa cada request manualmente.
useFileSystemPublicRoutes: false: desliga o roteamento automático baseado em arquivos de pages (útil com custom server pra evitar rotas duplicadas/SEO ruim); só desliga SSR, roteamento client-side ainda pode acessar essas rotas.
Incompatibilidade com output: standalone: standalone gera um server.js mínimo próprio e não traceia arquivos de custom server, os dois não podem ser usados juntos.
server.js não passa pelo Next.js Compiler: precisa ser compatível manualmente com a versão de Node.js 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: bootstrap mínimo de custom server delegando toda request ao handler do Next.js.

Reference Tables

Option	Type	Description
`conf`	Object	Mesmo objeto de `next.config.js`, default `{}`
`dev`	Boolean	Modo dev, default `false`
`dir`	String	Diretório do projeto, default `'.'`
`quiet`	Boolean	Esconde mensagens de erro com info do server
`hostname`	String	Hostname do servidor
`port`	Number	Porta do servidor
`httpServer`	node:http#Server	HTTP Server por trás do Next.js
`turbopack`	Boolean	Habilita Turbopack (default habilitado)
`webpack`	Boolean	Habilita webpack

Anti-patterns

Combinar custom server com output: standalone: incompatíveis, standalone ignora o custom server.
Assumir que useFileSystemPublicRoutes: false bloqueia navegação client-side: só desativa SSR por filename, ainda é preciso guardar redirects client-side (router.beforePopState).

Key Takeaways

Custom server é última opção, use só se o roteador integrado realmente não atende o requisito.
app.prepare() deve resolver antes de começar a aceitar requests.
Desligar file-system routing exige também tratar o lado client-side pra não vazar rotas indesejadas.

Connects To

ch292 Deploying: Node.js server é a base de deploy pra qualquer custom server.