Noções Básicas de Hono

Q: Hono funciona no Node 24?

Sim, via @hono/node-server. O mesmo código Hono pode ser implantado em Cloudflare Workers.

10 exemplos para construir APIs com Hono no Node.js - 7 básicos e 3 intermediários.

Pré-requisitos

mkdir hono-api && cd hono-api
npm init -y
npm pkg set type=module
npm install hono @hono/node-server
npm install -D typescript@5.6 tsx

Para decisões de portabilidade de tempo de execução, veja Hono no Node vs Edge.

Exemplos Básicos

1. Hello World no Node

import { Hono } from "hono";
import { serve } from "@hono/node-server";
 
const app = new Hono();
 
app.get("/", (c) => c.text("Hello from Hono\n"));
 
serve({ fetch: app.fetch, port: 3000 });

c é o objeto Context com helpers para tipos de resposta
app.fetch é um manipulador fetch Padrão Web
@hono/node-server faz a ponte entre Hono e o HTTP do Node

2. Resposta JSON

import { Hono } from "hono";
 
const app = new Hono();
 
app.get("/users", (c) => {
  return c.json([{ id: 1, name: "Ada Lovelace" }]);
});

c.json() define Content-Type: application/json
Retorne a Resposta diretamente dos manipuladores

3. Parâmetros de Rota e Query

import { Hono } from "hono";
 
const app = new Hono();
 
app.get("/users/:id", (c) => {
  const id = c.req.param("id");
  const include = c.req.query("include");
  return c.json({ id, include });
});

c.req.param() para parâmetros de caminho
c.req.query() para strings de consulta

4. POST com Corpo JSON

import { Hono } from "hono";
 
const app = new Hono();
 
app.post("/users", async (c) => {
  const body = await c.req.json<{ name: string; email: string }>();
  return c.json({ id: "1", ...body }, 201);
});

c.req.json() analisa o corpo de forma assíncrona
Código de status como segundo argumento para c.json()

5. Middleware

import { Hono } from "hono";
import { logger } from "hono/logger";
 
const app = new Hono();
 
app.use("*", logger());
app.use("/api/*", async (c, next) => {
  const start = Date.now();
  await next();
  c.header("X-Response-Time", `${Date.now() - start}ms`);
});

app.use(path, middleware) para middleware com escopo de caminho
await next() para continuar a cadeia
Middleware logger() embutido para log de requisições

6. Grupos de Rotas

import { Hono } from "hono";
 
const users = new Hono();
users.get("/", (c) => c.json([]));
users.get("/:id", (c) => c.json({ id: c.req.param("id") }));
 
const app = new Hono();
app.route("/users", users);

app.route(prefix, subApp) monta grupos de rotas
Cada sub-app é uma instância Hono independente

7. Tratamento de Erros

import { Hono } from "hono";
import { HTTPException } from "hono/http-exception";
 
const app = new Hono();
 
app.get("/users/:id", (c) => {
  const id = c.req.param("id");
  if (id === "999") throw new HTTPException(404, { message: "Not found" });
  return c.json({ id });
});
 
app.onError((err, c) => {
  if (err instanceof HTTPException) {
    return c.json({ error: err.message }, err.status);
  }
  return c.json({ error: "Internal server error" }, 500);
});

HTTPException para erros operacionais com códigos de status
app.onError() para tratamento centralizado de erros

Exemplos Intermediários

8. Variáveis de Contexto Tipadas

import { Hono } from "hono";
import { createMiddleware } from "hono/factory";
 
type Variables = { userId: string };
 
const app = new Hono<{ Variables: Variables }>();
 
const auth = createMiddleware<{ Variables: Variables }>(async (c, next) => {
  c.set("userId", "user-42");
  await next();
});
 
app.use("/api/*", auth);
app.get("/api/me", (c) => c.json({ userId: c.get("userId") }));

Tipo genérico Variables para c.set() / c.get()
createMiddleware para fábricas de middleware tipadas

9. CORS e Segurança

import { Hono } from "hono";
import { cors } from "hono/cors";
import { secureHeaders } from "hono/secure-headers";
 
const app = new Hono();
app.use("*", cors({ origin: "https://app.example.com" }));
app.use("*", secureHeaders());

Middleware de CORS e cabeçalhos de segurança embutidos
Nenhuma dependência externa helmet necessária

10. Validação com Zod

import { Hono } from "hono";
import { zValidator } from "@hono/zod-validator";
import { z } from "zod";
 
const app = new Hono();
 
const schema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});
 
app.post("/users", zValidator("json", schema), (c) => {
  const body = c.req.valid("json");
  return c.json({ id: "1", ...body }, 201);
});

@hono/zod-validator integra Zod com Hono
c.req.valid("json") retorna dados tipados e validados

FAQs

Quando devo escolher Hono em vez de Express ou Fastify?

Hono para portabilidade de edge, pegada mínima ou alinhamento com Padrões Web. Express/Fastify para o ecossistema Node maior. Veja Checklist de Seleção de Framework.

Hono funciona no Node 24?

Sim, via @hono/node-server. O mesmo código Hono pode ser implantado em Cloudflare Workers.

Hono está pronto para produção?

Sim. Usado em produção no Cloudflare Workers e Node. Ecossistema menor que Express/Fastify.

Como Hono se compara em tamanho?

~14KB minificado vs Express ~200KB+ com middleware. Importa para cold starts de edge.

Posso usar Hono com TypeScript?

Suporte TypeScript de primeira classe com contexto tipado, validadores e parâmetros de rota.

Relacionado

Hono no Node vs Edge - ADR de tempo de execução
Koa & Polka - outras opções leves
Noções Básicas de Express - alternativa principal
Checklist de Seleção de Framework - matriz de decisão
Melhores Práticas de 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.

Pré-requisitos

mkdir hono-api && cd hono-api
npm init -y
npm pkg set type=module
npm install hono @hono/node-server
npm install -D typescript@5.6 tsx

Para decisões de portabilidade de tempo de execução, veja Hono no Node vs Edge.

Exemplos Básicos

1. Hello World no Node

import { Hono } from "hono";
import { serve } from "@hono/node-server";
 
const app = new Hono();
 
app.get("/", (c) => c.text("Hello from Hono\n"));
 
serve({ fetch: app.fetch, port: 3000 });

c é o objeto Context com helpers para tipos de resposta
app.fetch é um manipulador fetch Padrão Web
@hono/node-server faz a ponte entre Hono e o HTTP do Node

2. Resposta JSON

import { Hono } from "hono";
 
const app = new Hono();
 
app.get("/users", (c) => {
  return c.json([{ id: 1, name: "Ada Lovelace" }]);
});

c.json() define Content-Type: application/json
Retorne a Resposta diretamente dos manipuladores

3. Parâmetros de Rota e Query

import { Hono } from "hono";
 
const app = new Hono();
 
app.get("/users/:id", (c) => {
  const id = c.req.param("id");
  const include = c.req.query("include");
  return c.json({ id, include });
});

c.req.param() para parâmetros de caminho
c.req.query() para strings de consulta

4. POST com Corpo JSON

import { Hono } from "hono";
 
const app = new Hono();
 
app.post("/users", async (c) => {
  const body = await c.req.json<{ name: string; email: string }>();
  return c.json({ id: "1", ...body }, 201);
});

c.req.json() analisa o corpo de forma assíncrona
Código de status como segundo argumento para c.json()

5. Middleware

import { Hono } from "hono";
import { logger } from "hono/logger";
 
const app = new Hono();
 
app.use("*", logger());
app.use("/api/*", async (c, next) => {
  const start = Date.now();
  await next();
  c.header("X-Response-Time", `${Date.now() - start}ms`);
});

app.use(path, middleware) para middleware com escopo de caminho
await next() para continuar a cadeia
Middleware logger() embutido para log de requisições

6. Grupos de Rotas

import { Hono } from "hono";
 
const users = new Hono();
users.get("/", (c) => c.json([]));
users.get("/:id", (c) => c.json({ id: c.req.param("id") }));
 
const app = new Hono();
app.route("/users", users);

app.route(prefix, subApp) monta grupos de rotas
Cada sub-app é uma instância Hono independente

7. Tratamento de Erros

import { Hono } from "hono";
import { HTTPException } from "hono/http-exception";
 
const app = new Hono();
 
app.get("/users/:id", (c) => {
  const id = c.req.param("id");
  if (id === "999") throw new HTTPException(404, { message: "Not found" });
  return c.json({ id });
});
 
app.onError((err, c) => {
  if (err instanceof HTTPException) {
    return c.json({ error: err.message }, err.status);
  }
  return c.json({ error: "Internal server error" }, 500);
});

HTTPException para erros operacionais com códigos de status
app.onError() para tratamento centralizado de erros

Exemplos Intermediários

8. Variáveis de Contexto Tipadas

import { Hono } from "hono";
import { createMiddleware } from "hono/factory";
 
type Variables = { userId: string };
 
const app = new Hono<{ Variables: Variables }>();
 
const auth = createMiddleware<{ Variables: Variables }>(async (c, next) => {
  c.set("userId", "user-42");
  await next();
});
 
app.use("/api/*", auth);
app.get("/api/me", (c) => c.json({ userId: c.get("userId") }));

Tipo genérico Variables para c.set() / c.get()
createMiddleware para fábricas de middleware tipadas

9. CORS e Segurança

import { Hono } from "hono";
import { cors } from "hono/cors";
import { secureHeaders } from "hono/secure-headers";
 
const app = new Hono();
app.use("*", cors({ origin: "https://app.example.com" }));
app.use("*", secureHeaders());

Middleware de CORS e cabeçalhos de segurança embutidos
Nenhuma dependência externa helmet necessária

10. Validação com Zod

import { Hono } from "hono";
import { zValidator } from "@hono/zod-validator";
import { z } from "zod";
 
const app = new Hono();
 
const schema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});
 
app.post("/users", zValidator("json", schema), (c) => {
  const body = c.req.valid("json");
  return c.json({ id: "1", ...body }, 201);
});

@hono/zod-validator integra Zod com Hono
c.req.valid("json") retorna dados tipados e validados

FAQs

Quando devo escolher Hono em vez de Express ou Fastify?

Hono para portabilidade de edge, pegada mínima ou alinhamento com Padrões Web. Express/Fastify para o ecossistema Node maior. Veja Checklist de Seleção de Framework.

Hono funciona no Node 24?

Sim, via @hono/node-server. O mesmo código Hono pode ser implantado em Cloudflare Workers.

Hono está pronto para produção?

Sim. Usado em produção no Cloudflare Workers e Node. Ecossistema menor que Express/Fastify.

Como Hono se compara em tamanho?

~14KB minificado vs Express ~200KB+ com middleware. Importa para cold starts de edge.

Posso usar Hono com TypeScript?

Suporte TypeScript de primeira classe com contexto tipado, validadores e parâmetros de rota.

Relacionado

Hono no Node vs Edge - ADR de tempo de execução
Koa & Polka - outras opções leves
Noções Básicas de Express - alternativa principal
Checklist de Seleção de Framework - matriz de decisão
Melhores Práticas de 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.

Noções Básicas de Hono

Buscar na documentação

Noções Básicas de Hono