Hono

To generate a Hono template, define the client property to be hono and a template of Hono will be generated in the target file and directory. For further details, visit the Hono documentation.

Example of orval.config.js

1module.exports = {
2  petstore: {
3    input: {
4      target: './petstore.yaml',
5    },
6    output: {
7      mode: 'split',
8      client: 'hono',
9      target: 'src/petstore.ts',
10      override: {
11        hono: {
12          handlers: 'src/handlers',
13        },
14      },
15    },
16  },
17};

Generating the Template

Orval generates files as follows:

1src/
2├── handlers
3│   ├── createPets.ts
4│   ├── listPets.ts
5│   ├── showPetById.ts
6│   └── updatePets.ts
7├── index.ts
8├── petstore.context.ts
9├── petstore.schemas.ts
10├── petstore.ts
11├── petstore.validator.ts
12└── petstore.zod.ts

• petstore.ts: Initializes Hono and defines endpoints.
• handlers: Contains templates for each endpoint.
• petstore.schemas.ts: Defines request and response schemas.
• petstore.validator.ts: Implements Hono validator.
• petstore.zod.ts: Defines schemas using Zod for validation.
• petstore.context.ts: Defines context for endpoints.

Implementing an Endpoint Process Handler

Orval generates a handler template for Hono. For example, see listPets.ts. Validation is defined for request and response. Only the actual processing is not implemented.

1import { createFactory } from 'hono/factory';
2import { zValidator } from '../petstore.validator';
3import { ListPetsContext } from '../petstore.context';
4import { listPetsQueryParams, listPetsResponse } from '../petstore.zod';
5
6const factory = createFactory();
7
8export const listPetsHandlers = factory.createHandlers(
9  zValidator('query', listPetsQueryParams),
10  zValidator('response', listPetsResponse),
11  async (c: ListPetsContext) => {},
12);

It is possible to implement the API by defining the response according to the response schema.

1import { createFactory } from 'hono/factory';
2import { zValidator } from '../petstore.validator';
3import { ListPetsContext } from '../petstore.context';
4import { listPetsQueryParams, listPetsResponse } from '../petstore.zod';
5
6const factory = createFactory();
7
8export const listPetsHandlers = factory.createHandlers(
9  zValidator('query', listPetsQueryParams),
10  zValidator('response', listPetsResponse),
11  async (c: ListPetsContext) => {
12+    return c.json([
13+      {
14+        id: 1,
15+        name: 'doggie',
16+      },
17+    ]);
18  },
19);

Run Hono Dev Server

Use the wrangler dev command to run the Hono dev server. Set the entrypoint as src/petstore.ts instead of src/index.ts.

1yarn wrangler dev src/petstore.ts
2curl http://localhost:8787/pets #=> [{"id":1,"name":"doggie"}]

See the full example here. To develop the frontend and backend with TypeScript using Hono, Fetch, and Next.js, see the sample app here.

Using Composite Routes and Handlers Split by Tags in OpenAPI

If you want to use tags or tags-split mode, which splits handlers by tags defined in OpenAPI, but want to generate a composite single Hono route file, define a file path such as src/routes.ts to the override.hono.compositeRoute property and the Hono template generates a composite root file in the target file and directory.

1module.exports = {
2  petstore: {
3    input: {
4      target: './petstore.yaml',
5    },
6    output: {
7      mode: 'tags-split',
8      client: 'hono',
9      target: 'src/endpoints',
10      schemas: 'src/schemas',
11      override: {
12        hono: {
13          compositeRoute: 'src/routes.ts',
14        },
15      },
16    },
17  },
18};

The files will be generated as below:

1src/
2├── endpoints
3│   ├── pets
4│   │   ├── pets.context.ts
5│   │   ├── pets.handlers.ts
6│   │   └── pets.zod.ts
7│   └── validator.ts
8├── routes.ts
9└── schemas
10    ├── pet.ts
11    └── pets.ts

routes.ts composes all routes as shown below:

1import { Hono } from 'hono';
2import {
3  listPetsHandlers,
4  createPetsHandlers,
5  updatePetsHandlers,
6  showPetByIdHandlers,
7} from './endpoints/pets/pets.handlers';
8
9const app = new Hono();
10
11app.get('/pets', ...listPetsHandlers);
12app.post('/pets', ...createPetsHandlers);
13app.put('/pets', ...updatePetsHandlers);
14app.get('/pets/:petId', ...showPetByIdHandlers);
15
16export default app;

Prepare a Hono server like app.ts and embed it:

1import { Hono } from 'hono';
2import routes from './routes';
3
4const app = new Hono();
5
6app.route('/', routes);
7
8export default app;

Run the Hono dev server as usual.

1yarn wrangler dev src/app.ts
2curl http://localhost:8787/pets #=> [{"id":1,"name":"doggie"}]

See the full example here.