@typeful-api/hono

Hono adapter for typeful-api — build end-to-end type-safe OpenAPI-first APIs with Hono. Works on Node.js, Cloudflare Workers, Deno, Bun, and more.

Installation

npm install @typeful-api/core @typeful-api/hono hono @hono/zod-openapi zod

Quick Start

1. Define Your Contract

import { defineApi, route } from '@typeful-api/core';
import { z } from 'zod';

const api = defineApi({
  v1: {
    children: {
      hello: {
        routes: {
          greet: route
            .get('/')
            .returns(z.object({ message: z.string() }))
            .withSummary('Say hello'),
        },
      },
    },
  },
});

2. Create a Router

import { Hono } from 'hono';
import { createHonoRouter } from '@typeful-api/hono';

const router = createHonoRouter(api, {
  v1: {
    hello: {
      greet: async () => ({ message: 'Hello, World!' }),
    },
  },
});

const app = new Hono();
app.route('/api', router);

export default app;

Typed Environment

Use WithVariables to compose context types for Hono's bindings and variables:

import { createHonoRouter, WithVariables } from '@typeful-api/hono';

type BaseEnv = { Bindings: { DATABASE_URL: string } };
type WithDb = WithVariables<BaseEnv, { db: Database }>;
type WithAuth = WithVariables<WithDb, { user: User }>;

const router = createHonoRouter<
  typeof api,
  {
    v1: {
      products: WithDb;
      users: WithAuth;
    };
  }
>(api, {
  v1: {
    products: {
      list: async ({ c }) => {
        const db = c.get('db');
        return await db.products.findMany();
      },
    },
  },
});

Hierarchical Middleware

Apply middleware at version, group, or route level:

const router = createHonoRouter(api, {
  v1: {
    middlewares: [corsMiddleware], // All v1 routes
    products: {
      middlewares: [dbMiddleware], // All product routes
      list: handler,
      create: handler,
    },
  },
});

Handlers in Separate Files

Derive handler types from the contract for type-safe standalone handler files:

import type { InferHonoHandlersWithVars } from '@typeful-api/hono';
import type { api } from './api';

type AppHandlers = InferHonoHandlersWithVars<typeof api, { db: Database }>;
export type ProductHandlers = AppHandlers['v1']['products'];

import type { ProductHandlers } from '../types';

export const list: ProductHandlers['list'] = async ({ c }) => {
  const db = c.get('db');
  return await db.products.findMany();
};

API

| Export | Description | | -------------------------------------- | ----------------------------------------------- | | createHonoRouter(contract, handlers) | Create a typed Hono router from an API contract | | createHonoRegistry() | Create an OpenAPI registry for spec generation | | composeMiddleware(...mw) | Compose multiple Hono middlewares | | conditionalMiddleware(pred, mw) | Apply middleware conditionally | | createTypedMiddleware(fn) | Create middleware with typed context | | createVariableMiddleware(fn) | Create middleware that sets context variables | | getVariables(c) | Get typed variables from Hono context |

Type Utilities

| Export | Description | | --------------------------- | -------------------------------------------- | | InferHonoHandlers | Infer handler types from a contract | | InferHonoGroupHandlers | Infer handler types for a specific group | | InferHonoHandlersWithVars | Infer handlers with shared context variables | | WithVariables<Env, Vars> | Compose Hono environment types |

Documentation

For full documentation, examples, and guides, visit the typeful-api repository.

License

MIT