Project Structure

Overview

The repository structure of Hono organizes its codebase around clear boundaries for core application logic, execution contexts, platform-specific runtime adapters, pluggable routers, and dual-runtime JSX rendering. Top-level configuration files such as package.json and jsr.json establish dual distribution metadata for both npm and Presets and Builds, mapping fine-grained export subpaths across utilities, helpers, middleware, and adapters.

Sources: package.json:119-276, jsr.json:1-106

Top-level directory layout

Dual Distribution and Package Metadata

Hono uses dual publishing configuration formats via package.json and jsr.json at the repository root, ensuring compatibility across both the npm ecosystem and the JSR registry. The JSR manifest defines package identification under @hono/hono at version 0.0.0, configures compiler options targeting ["dom", "dom.iterable", "deno.ns"], and enables unstable features including sloppy-imports. Its publication filter explicitly includes jsr.json, LICENSE, README.md, and all TypeScript files under src/**/*.ts, while excluding test suites matching src/**/*.test.ts and src/**/*.test.tsx.

Copy{
  "name": "@hono/hono",
  "version": "0.0.0",
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "deno.ns"]
  },
  "unstable": ["sloppy-imports"]
}

Sources: jsr.json:1-110

Export Subpath Mapping

Export mappings link fine-grained module subpaths to specific build targets for dual packaging. The npm distribution points conditional exports (types, import, require) to compiled output files under ./dist/, while jsr.json maps identical subpaths directly to their corresponding TypeScript source modules under ./src/.

Sources: jsr.json:8-106, package.json:119-276

Compiler Configuration and Test Spec

TypeScript compilation for tests is governed by tsconfig.spec.json, which extends ./tsconfig.base.json. It configures JSX compilation via "jsx": "react-jsx", sets the JSX import source to "hono/jsx", suppresses output emission with "noEmit": true, restricts the root directory to ./src, and injects "vitest/globals" into the type definitions while including source files and src/middleware/jwk/keys.test.json.

Copy{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "hono/jsx",
    "noEmit": true,
    "rootDir": "./src",
    "types": ["vitest/globals"]
  },
  "include": ["src", "src/middleware/jwk/keys.test.json"]
}

Sources: tsconfig.spec.json:1-11

Source tree architecture

Core Engine and Entrypoints

The main entry point for the framework is defined in src/index.ts, which exports the primary Hono application class alongside essential types and abstractions. Core framework primitives are exported directly from their respective internal modules, including Context, HonoRequest, and type definitions covering environment variables, error handlers, handlers, middleware handlers, request/response inference types, and input definitions.

Copyimport { Hono } from './hono'
 
/**
 * Types for environment variables, error handlers, handlers, middleware handlers, and more.
 */
export type {
  Env,
  ErrorHandler,
  Handler,
  MiddlewareHandler,
  Next,
  NotFoundResponse,
  NotFoundHandler,
  Input,
} from './types'
/**
 * Types for context, context variable map, context renderer, and execution context.
 */
export { Context } from './context'
export type { ContextVariableMap, ContextRenderer, ExecutionContext } from './context'
/**
 * Type for HonoRequest.
 */
export type { HonoRequest } from './request'
/**
 * Types for inferring request and response types and client request options.
 */
export type { InferRequestType, InferResponseType, ClientRequestOptions } from './client'
 
/**
 * Hono framework for building web applications.
 */
export { Hono }

Sources: src/index.ts:17-53

Internal Module Boundaries

The src/ directory isolates core routing engine code, request-response execution handling, middleware implementations, helper utilities, and platform adapters into dedicated boundaries. Package exports map fine-grained features such as middleware for CORS, CSRF, JWT validation, ETag generation, security headers, and logging directly to their corresponding subdirectories within src/.

Sources: package.json:123-272

Router implementation subdirectories

Specialized Routing Engines

Hono isolates its routing algorithms into dedicated subdirectories under src/router/, exposing distinct strategies for route compilation and matching. Each specialized router package exports its engine class via its entry point module.

Sources: src/router/reg-exp-router/index.ts:1-7

RegExpRouter and Preparation Helpers

The reg-exp-router implementation exports both RegExpRouter and preparation utilities like PreparedRegExpRouter, buildInitParams, and serializeInitParams.

Sources: src/router/reg-exp-router/index.ts:6-7

Trie, Smart, and Linear Routers

Additional router implementations include TrieRouter, SmartRouter, and LinearRouter, each exported from its respective subdirectory.

Sources: src/router/trie-router/index.ts:1-6, src/router/smart-router/index.ts:1-6, src/router/linear-router/index.ts:1-6

Platform adapter organization

Handler Bindings and Asset Serving

Runtime integration modules inside src/adapter/ map native platform request events and environment bindings to the framework's core request-response cycle. For Cloudflare Pages, handle converts incoming EventContext payloads into app.fetch invocations, injecting eventContext into environment bindings alongside waitUntil and passThroughOnException lifecycle controls.

Copyexport const handle =
  <E extends Env = Env, S extends Schema = BlankSchema, BasePath extends string = '/'>(
    app: Hono<E, S, BasePath>
  ): PagesFunction<E['Bindings']> =>
  (eventContext) => {
    return app.fetch(
      eventContext.request,
      { ...eventContext.env, eventContext },
      {
        waitUntil: eventContext.waitUntil,
        passThroughOnException: eventContext.passThroughOnException,
        props: {},
      }
    )
  }

Sources: src/adapter/cloudflare-pages/handler.ts:32-46

Advanced Pages configurations utilize serveStatic, which queries the ASSETS fetcher binding directly from the environment and triggers c.notFound() when asset requests return a 404 status code.

Copyexport const serveStatic = (): MiddlewareHandler => {
  return async (c) => {
    const env = c.env as { ASSETS: FetcherLike }
    const res = await env.ASSETS.fetch(c.req.raw)
    if (res.status === 404) {
      return c.notFound()
    }
    return res
  }
}

Sources: src/adapter/cloudflare-pages/handler.ts:114-123

Connection Metadata and Target Exports

Netlify deployment integration exports its request handler and connection information resolver through a unified adapter entry point module.

Sources: src/adapter/netlify/mod.ts:1-2, src/adapter/cloudflare-pages/handler.ts:32-123

Client JSX subtrees

DOM and Client Runtime Organization

Hono partitions its JSX rendering engine into distinct server-side string serialization paths and client-side browser DOM execution subtrees. The client DOM runtime modules reside under src/jsx/dom/, providing browser-native rendering mechanisms, interactive hooks like useState and useEffect, and dedicated package exports in package.json.

Copyexport { jsxDEV as jsx, Fragment } from './jsx-dev-runtime'
export { jsxDEV as jsxs } from './jsx-dev-runtime'
export type { JSX } from './jsx-dev-runtime'

Sources: src/jsx/dom/jsx-runtime.ts:6-8

Subtree Package Exports

Export definitions in package.json expose specialized subpath entries for server-side JSX helpers, streaming renderers, and client-side DOM bundles.

Sources: package.json:153-207

Related

• Overview
• Presets and Builds