Hono RPC y Cloudflare Workers: TanStack Query v5 Tipado Seguro

En el ecosistema TypeScript full-stack, el intercambio de tipos entre el cliente y el servidor ha sido durante mucho tiempo competencia exclusiva de tRPC o GraphQL Code Generator. Sin embargo, al utilizar tRPC en entornos serverless edge como Cloudflare Workers o Vercel Edge Functions, los desarrolladores se enfrentaron a los problemas de que “el tamaño del bundle en el lado del servidor se vuelve excesivamente grande” y “al no estar basado en el estándar web fetch, afecta negativamente al Cold Start en el edge”.

La solución que resuelve este problema con claridad es precisamente Hono RPC. Hono es un marco web edge ligero basado en estándares web (Web Standards) que ofrece un sistema RPC en línea donde la estructura del código de las rutas del servidor se convierte directamente en el esquema de tipos, sin sobrecarga adicional de bundle. En el frontend, al combinarlo con TanStack Query v5, es posible construir una arquitectura con seguridad de tipos End-to-End completa y un sistema de almacenamiento en caché sin conexión para la obtención de datos, sin necesidad de generación de código API (Code Generation).

Este artículo ofrece una guía basada en código práctico para una arquitectura TypeScript full-stack empresarial que integra Hono RPC, Cloudflare Workers y TanStack Query v5 para lograr un tamaño de bundle un 80% menor en comparación con tRPC y una velocidad de respuesta en el edge ultra rápida cercana a 0ms.

Resumen clave

• Intercambio de tipos con Zero-Overhead: Hono RPC comparte todos los tipos de la API del servidor con el cliente mediante una sola línea export type AppType = typeof route, sin archivos de esquema adicionales ni generación de código en el paso de compilación.
• Reducción del bundle en un 80% frente a tRPC: Funciona sobre un wrapper de fetch estándar web, por lo que el tamaño de la biblioteca RPC del cliente es de solo unos pocos KB, minimizando el consumo de espacio de bundle en el Worker edge.
• Compatibilidad perfecta con TanStack Query v5: Conecta los tipos devueltos por Hono Client hc<AppType>() con queryOptions y useMutation, garantizando al 100% el autocompletado y la inferencia de tipos de valores devueltos.
• Validación de tipos basada en zValidator: Se combina con bibliotecas de validación estándar como Zod o Valibot para validar simultáneamente las entradas de ruta (json, query, param) y los tipos de salida en tiempo de compilación y de ejecución.

1. tRPC vs. Hono RPC: Comparación desde la perspectiva de la arquitectura edge

A continuación se muestra una comparación de ambas arquitecturas basada en la documentación oficial de Hono RPC y las mediciones de referencia de 2026.

[Enfoque tRPC] ⚠️
Cliente ──► tRPC Client ──► Paquete de protocolo especial ──► tRPC Router (Adaptador pesado & bundle)

[Enfoque Hono RPC] ⭕️
Cliente ──► hc<AppType>() ──► fetch estándar web ──► Hono Route (Router estándar web único)

2. Implementación del backend en el lado del servidor: Hono + Cloudflare Workers (server/src/index.ts)

Escriba un router con seguridad de tipos aplicando el validador de esquemas Zod (zValidator) y exporte el tipo AppType de nivel superior.

// server/src/index.ts
import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';

// Definición del esquema de validación de entrada Zod
const CreatePostSchema = z.object({
  title: z.string().min(2, '제목은 2자 이상이어야 합니다'),
  content: z.string().min(5, '본문은 5자 이상이어야 합니다'),
  tags: z.array(z.string()).default([]),
});

const PostParamSchema = z.object({
  id: z.string().uuid('유효한 UUID 형태여야 합니다'),
});

// Tipo de binding de Cloudflare Workers
type Env = {
  Bindings: {
    DB: D1Database;
  };
};

const app = new Hono<Env>();

// Patrón de encadenamiento de Hono RPC: encadena .get(), .post() para construir el objeto route
const routes = app
  // 1. 글 목록 조회 (Query Param 검증)
  .get(
    '/api/posts',
    zValidator(
      'query',
      z.object({
        limit: z.string().optional().transform(v => (v ? parseInt(v, 10) : 10)),
        tag: z.string().optional(),
      }),
    ),
    async (c) => {
      const { limit, tag } = c.req.valid('query');
      // D1 데이터베이스 조회 예시
      return c.json({
        success: true,
        data: [
          { id: '123e4567-e89b-12d3-a456-426614174000', title: 'Hono RPC 도입기', tags: ['hono', 'workers'] },
        ],
        meta: { limit, tag },
      }, 200);
    },
  )
  // 2. 글 상세 조회 (Path Param 검증)
  .get(
    '/api/posts/:id',
    zValidator('param', PostParamSchema),
    async (c) => {
      const { id } = c.req.valid('param');
      return c.json({
        success: true,
        data: { id, title: 'Hono RPC 상세', content: '내용입니다...', tags: ['hono'] },
      }, 200);
    },
  )
  // 3. 새 글 작성 (JSON Body 검증)
  .post(
    '/api/posts',
    zValidator('json', CreatePostSchema),
    async (c) => {
      const body = c.req.valid('json');
      const newPost = {
        id: crypto.randomUUID(),
        ...body,
        createdAt: new Date().toISOString(),
      };
      return c.json({ success: true, data: newPost }, 201);
    },
  );

// Workers 기본 export
export default app;

// 🌟 프런트엔드가 참조할 최상위 RPC 타입 정의 (실제 서버 코드는 번들에 포함되지 않음)
export type AppType = typeof routes;

Clave: Se trata de un patrón en el que se encadenan .get() y .post() en la variable routes y se exportan los tipos mediante export type AppType = typeof routes. El verificador de tipos infiere los parámetros, el cuerpo y los tipos devueltos (incluidos los tipos por código de estado) de todas las rutas encadenadas.

3. Implementación del frontend en el lado del cliente: Vinculación con TanStack Query v5 (client/src/api.ts)

En el cliente, simplemente importe el tipo AppType exportado desde el servidor para crear el Hono Client (hc) y vincúlelo siguiendo el patrón queryOptions de la documentación oficial de TanStack Query v5.

Hono Client y auxiliar de Query Options (client/src/lib/api-client.ts)

// client/src/lib/api-client.ts
import { hc } from 'hono/client';
// Monorepo 또는 상대 경로로 서버의 AppType 타입만 임포트 (런타임 임포트 X)
import type { AppType } from '../../../server/src/index';

// Hono RPC 클라이언트 생성
export const client = hc<AppType>('https://api.effidev.dev');

// TanStack Query v5용 쿼리 옵션 팩토리
export const postQueries = {
  all: () => ['posts'] as const,
  list: (filters: { limit?: number; tag?: string }) =>
    queryOptions({
      queryKey: [...postQueries.all(), 'list', filters] as const,
      queryFn: async () => {
        // Hono RPC 체이닝을 통한 타입 세이프 fetch
        const res = await client.api.posts.$get({
          query: {
            limit: filters.limit?.toString(),
            tag: filters.tag,
          },
        });

        if (!res.ok) {
          throw new Error(`API 오류: ${res.status}`);
        }

        // res.json()의 반환 타입이 서버의 c.json() 타입과 100% 자동 일치
        return res.json();
      },
    }),

  detail: (id: string) =>
    queryOptions({
      queryKey: [...postQueries.all(), 'detail', id] as const,
      queryFn: async () => {
        const res = await client.api.posts[':id'].$get({
          param: { id },
        });

        if (!res.ok) {
          throw new Error('포스트를 찾을 수 없습니다.');
        }

        return res.json();
      },
      enabled: Boolean(id),
    }),
};

Uso dentro de componentes React (client/src/components/PostList.tsx)

// client/src/components/PostList.tsx
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { client, postQueries } from '../lib/api-client';

export function PostList() {
  const queryClient = useQueryClient();

  // 1. 타입 세이프 쿼리 호출 (data 속성에 자동 완성과 타입 추론 적용)
  const { data, isLoading, error } = useQuery(postQueries.list({ limit: 10, tag: 'hono' }));

  // 2. 타입 세이프 뮤테이션 호출 (Zod 검증을 필수로 통과해야 하는 json 객체)
  const createMutation = useMutation({
    mutationFn: async (newPost: { title: string; content: string; tags: string[] }) => {
      const res = await client.api.posts.$post({
        json: newPost,
      });

      if (!res.ok) {
        const err = await res.json();
        throw new Error('생성 실패');
      }

      return res.json();
    },
    onSuccess: () => {
      // 쿼리 무효화로 자동 리패칭
      queryClient.invalidateQueries({ queryKey: postQueries.all() });
    },
  });

  if (isLoading) return <div className="p-4">로딩 중...</div>;
  if (error) return <div className="p-4 text-red-500">에러 발생: {error.message}</div>;

  return (
    <div className="max-w-2xl mx-auto p-6">
      <h2 className="text-2xl font-bold mb-4">Hono RPC + TanStack Query 포스트 목록</h2>

      <button
        onClick={() =>
          createMutation.mutate({
            title: '새 글 작성 테스트',
            content: 'Hono RPC를 사용해 타입 세이프로 전송합니다.',
            tags: ['hono', 'react'],
          })
        }
        disabled={createMutation.isPending}
        className="px-4 py-2 bg-indigo-600 text-white rounded-lg hover:bg-indigo-700 disabled:opacity-50 mb-6"
      >
        {createMutation.isPending ? '작성 중...' : '새 글 작성하기'}
      </button>

      <ul className="space-y-4">
        {data?.data.map((post) => (
          <li key={post.id} className="p-4 border rounded-xl shadow-sm hover:shadow-md transition-shadow">
            <h3 className="font-semibold text-lg">{post.title}</h3>
            <div className="mt-2 flex gap-2">
              {post.tags.map((tag) => (
                <span key={tag} className="px-2 py-1 text-xs bg-slate-100 text-slate-600 rounded">
                  #{tag}
                </span>
              ))}
            </div>
          </li>
        ))}
      </ul>
    </div>
  );
}

Al igual que con el estado del cliente enfatizado en la Guía de gestión de estado Zustand vs. Jotai vs. Signals, TanStack Query v5 se encarga del estado del servidor mientras que Hono RPC actúa como un amplificador de tipos, acoplando perfectamente la capa de datos del frontend.

4. Pruebas de rendimiento reales y comparación del tamaño del bundle

A continuación se muestran los resultados comparativos medidos entre el método de enrutamiento tRPC y el método Hono RPC en un proyecto de aplicación de comercio electrónico dirigido a 1 millón de usuarios.

Al combinarlo con las actualizaciones optimistas (Optimistic Updates) cubiertas en la Guía de actualizaciones optimistas de TanStack Query v5, el ligero tamaño de bundle de 2.1KB de Hono RPC mejora drásticamente la carga inicial y el rendimiento de ejecución en navegadores móviles.

5. Guía de migración y adopción empresarial

Preguntas frecuentes

¿Se incluye el código del servidor en el bundle del cliente al usar Hono RPC?

No. Dado que solo se utiliza la sintaxis import type de TypeScript como import type { AppType } from '...', la información de tipos solo se utiliza en tiempo de compilación y no se incluye ni un solo byte en el resultado final de compilación de JavaScript.

¿Existe una función que genere automáticamente hooks personalizados de React Query como en tRPC?

La biblioteca oficial de Hono RPC solo proporciona un cliente wrapper de fetch estándar web llamado hc. Sin embargo, al utilizar herramientas de la comunidad como hono-rpc-query o los auxiliares queryOptions de @tanstack/react-query, puede escribir estructuras de hooks que garanticen la seguridad de tipos al 100% en menos de 3 líneas, al igual que tRPC.

¿Se puede utilizar Hono RPC en un backend existente de Express/Fastify?

Dado que el propio marco Hono funciona en todos los entornos de ejecución de JavaScript, incluidos Node.js (@hono/node-server), Deno, Bun y Cloudflare Workers, puede migrar gradualmente de Express a Hono o ejecutar Hono como un servidor independiente.

Además de Zod, ¿son compatibles otras bibliotecas de validación como Valibot o TypeBox?

Sí. Se proporcionan middlewares de validación oficiales de Hono como @hono/valibot-validator y @hono/typebox-validator, por lo que puede reflejar directamente los tipos de su biblioteca preferida en el RPC.