chanfana

library3.3.0jsnpmunverified

chanfana (formerly itty-router-openapi) is a library that adds OpenAPI 3 and 3.1 schema generation and validation to any router, primarily targeting Hono and itty-router. Version 3.3.0, released by Cloudflare, emphasizes Cloudflare Workers but works on any runtime. Key differentiators: Zod v4 compatible with full TypeScript inference, class-based endpoints, CLI to extract schema, and extending existing apps without modifying old routes. Release cadence is active with frequent updates. Pairs with Hono, itty-router, and zod.

devops

npm install chanfana

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CHANFANA

chanfana

devopsjavascriptv3.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fromHono

✓ import { fromHono } from 'chanfana'

✗ import { FromHono } from 'chanfana'

Case-sensitive; fromHono is a factory function, not a class

OpenAPIRoute

✓ import { OpenAPIRoute } from 'chanfana'

✗ const OpenAPIRoute = require('chanfana').OpenAPIRoute

ESM-only since v3; require() will fail in Node >=18

OpenAPIClient

✓ import { OpenAPIClient } from 'chanfana'

✗ import OpenAPIClient from 'chanfana'

Named export, not default export

Sets up an OpenAPI endpoint using chanfana with Hono, Zod validation, and Cloudflare Workers bindings.

import { fromHono, OpenAPIRoute } from 'chanfana'; import { Hono } from 'hono'; import { z } from 'zod'; import type { Context } from 'hono'; export type Env = { DB: D1Database; BUCKET: R2Bucket; }; export type AppContext = Context<{ Bindings: Env }>; class GetPageNumber extends OpenAPIRoute { schema = { request: { params: z.object({ id: z.string().min(2).max(10), }), query: z.object({ page: z.number().int().min(0).max(20), }), }, }; async handle(request: Request, env: Env, context: ExecutionContext) { const data = await this.getValidatedData(); return new Response(`Page ${data.query.page} for item ${data.params.id}`); } } const app = new Hono(); const openapi = fromHono(app, { schema: { info: { title: 'Example API', version: '1.0.0' } }, }); openapi.get('/api/items/:id', GetPageNumber); export default app;

Debug

Known issues

breakingchanfana v3 drops CommonJS support; only ESM is supported.

fix

Use import syntax instead of require(). Ensure package.json has 'type': 'module' or use .mjs extension.

affects: >=3.0.0

breakingRenamed from itty-router-openapi to chanfana. All imports must change.

fix

Replace 'itty-router-openapi' with 'chanfana' in package.json dependencies and all import statements.

affects: >=2.0.0

deprecatedOpenAPIRoute.schema now requires Zod v4 syntax; v3 schemas may break.

fix

Update Zod to v4 and adjust schema definitions (e.g., z.number().int() instead of z.number() for integer).

affects: >=3.0.0

gotchafromHono() must be called before adding routes; otherwise routes may not be registered.

fix

Call fromHono(app, options) immediately after creating the Hono app, before adding any routes.

affects: >=3.0.0

gotchaOpenAPIRoute subclasses must implement handle() method returning a Response or Promise<Response>.

fix

Ensure handler returns a proper Response object (e.g., new Response(...)).

affects: >=1.0.0

gotchaCLI npx chanfana requires wrangler to be configured and the worker to expose /openapi.json endpoint.

fix

Ensure wrangler.toml is present and that the OpenAPI schema endpoint is registered (usually via fromHono).

affects: >=3.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Trying to use ESM import in a CommonJS environment (e.g., using require to load ES module).

fix

Set 'type': 'module' in package.json or rename file to .mjs.

TypeError: OpenAPIRoute is not a constructor

Importing OpenAPIRoute as default instead of named import, or using CommonJS require incorrectly.

fix

Use correct named import: import { OpenAPIRoute } from 'chanfana'.

TypeError: fromHono is not a function

Incorrect import (likely default import) or using older version of chanfana.

fix

Ensure named import: import { fromHono } from 'chanfana'. Upgrade to v3+.

ZodError: Expected number, received string

Query parameter defined as number but actual value is string (HTTP query params are strings by default).

fix

Use z.coerce.number() or preprocess to parse string to number in schema.

Upgrade

Version history

3.3.0latest on npm

Audit

Dependencies

honooptionalPrimary router adapter; chanfana extends Hono with OpenAPI endpoints

itty-routeroptionalAlternative router adapter for OpenAPI

zodrequiredRequired for schema validation and TypeScript inference

Agent activity

15 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/cloudflare/chanfana ↗

packagechanfana ↗

homepagehttps://chanfana.pages.dev ↗