Koa & Polka

Entenda Koa e Polka como frameworks HTTP Node.js leves que você pode encontrar em bases de código legadas ou em implantações mínimas.

Receita

Referência rápida para reconhecer cada framework.

Koa (contexto async):

import Koa from "koa";
 
const app = new Koa();
app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  ctx.set("X-Response-Time", `${Date.now() - start}ms`);
});
app.use(async (ctx) => {
  ctx.body = { ok: true };
});
app.listen(3000);

Polka (roteador minimalista):

import polka from "polka";
 
const app = polka();
app.get("/users", (_req, res) => {
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify([{ id: 1 }]));
});
app.listen(3000);

Quando usar isso: Manter aplicações Koa legadas, ou quando você precisa do roteador HTTP absolutamente menor (Polka).

Exemplo de Trabalho

Comparação lado a lado do mesmo endpoint:

// --- Koa ---
import Koa from "koa";
import Router from "@koa/router";
import bodyParser from "koa-bodyparser";
 
const koaApp = new Koa();
const router = new Router({ prefix: "/api" });
 
koaApp.use(bodyParser());
router.get("/users/:id", async (ctx) => {
  ctx.body = { id: ctx.params.id, name: "Ada" };
});
koaApp.use(router.routes());
 
// --- Polka ---
import polka from "polka";
import { json } from "body-parser";
 
const polkaApp = polka();
polkaApp.use(json());
polkaApp.get("/api/users/:id", (req, res) => {
  const id = (req as { params: { id: string } }).params.id;
  res.end(JSON.stringify({ id, name: "Ada" }));
});
 
// --- Equivalente moderno: Hono ---
import { Hono } from "hono";
const honoApp = new Hono();
honoApp.get("/api/users/:id", (c) => c.json({ id: c.req.param("id"), name: "Ada" }));

O que isso demonstra:

• Koa usa ctx (contexto) em vez de (req, res)
• Middleware Koa é async-first (sem callback next())
• Polka é um roteador minimalista sobre Node HTTP puro
• Hono fornece uma alternativa moderna com footprint semelhante

Análise Detalhada

Comparação de Frameworks

Quando Você Ainda Vê Koa

• APIs Node.js mais antigas construídas por equipes que migraram do Express para o Koa (~2015-2020)
• Projetos que usam @koa/router, koa-bodyparser, koa-jwt
• Frameworks construídos sobre Koa (por exemplo, alguns servidores GraphQL)

Quando Você Ainda Vê Polka

• Microsserviços que precisam da menor camada HTTP possível
• Empacotado em ferramentas como sirv-cli e internos do adaptador @sveltejs/kit
• Serviços internos sensíveis ao desempenho com < 5 rotas

Armadilhas

• Iniciar novos projetos no Koa - o ecossistema está diminuindo. Correção: use Hono ou Fastify para novos trabalhos.
• Koa sem middleware de erro - erros assíncronos podem ser perdidos. Correção: use try/catch ou koa-error-handler.
• Polka sem parser de corpo - corpos POST ilegíveis. Correção: adicione middleware body-parser.
• Sem validação embutida em nenhum dos dois - manual ou adicione Zod/Ajv. Correção: use Hono com @hono/zod-validator.
• Migrando Koa para Hono - conceitos de middleware semelhantes, mas API diferente. Correção: reescreva rotas; os padrões de middleware são transferíveis.
• Assumir que Polka tem um ecossistema - é apenas um roteador. Correção: traga sua própria pilha de middleware.

Alternativas

FAQs

Relacionado

• Noções Básicas de Hono - alternativa moderna e leve
• Padrão de Middleware - conceitos de middleware
• Roteamento sem Frameworks - minimalismo no nível do Polka
• Checklist de Seleção de Framework - matriz de decisão
• Melhores Práticas para Frameworks Leves - checklist da seção

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.