--- title: "Project Structure" description: "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-runti..." last_updated: "2026-10-12T08:14:12.711203+00:00" canonical_url: "https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/getting-started/project-structure" ---
Relevant source files The following files were used as context for generating this wiki page: - [package.json](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/package.json) - [src/middleware/jsx-renderer/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/middleware/jsx-renderer/index.ts) - [src/jsx/jsx-runtime.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/jsx/jsx-runtime.ts) - [jsr.json](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/jsr.json) - [src/jsx/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/jsx/index.ts) - [src/types.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/types.ts) - [src/adapter/netlify/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/adapter/netlify/index.ts) - [src/context.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/context.ts) - [src/adapter/cloudflare-pages/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/adapter/cloudflare-pages/index.ts) - [src/helper/ssg/ssg.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/helper/ssg/ssg.ts) - [src/middleware/language/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/middleware/language/index.ts) - [src/adapter/netlify/mod.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/adapter/netlify/mod.ts) - [src/router.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/router.ts) - [src/preset/quick.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/preset/quick.ts) - [src/adapter/bun/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/adapter/bun/index.ts) - [src/router/reg-exp-router/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/router/reg-exp-router/index.ts) - [src/adapter/cloudflare-pages/handler.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/adapter/cloudflare-pages/handler.ts) - [vitest.config.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/vitest.config.ts) - [src/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/index.ts) - [src/adapter/vercel/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/adapter/vercel/index.ts) - [src/helper/ssg/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/helper/ssg/index.ts) - [src/jsx/dom/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/jsx/dom/index.ts) - [src/router/trie-router/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/router/trie-router/index.ts) - [src/jsx/base.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/jsx/base.ts) - [src/router/smart-router/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/router/smart-router/index.ts) - [src/middleware/jwt/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/middleware/jwt/index.ts) - [src/jsx/dom/jsx-runtime.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/jsx/dom/jsx-runtime.ts) - [src/middleware/request-id/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/middleware/request-id/index.ts) - [src/router/linear-router/index.ts](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/router/linear-router/index.ts) - [tsconfig.spec.json](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/tsconfig.spec.json)
## Overview The repository structure of Hono organizes its codebase around clear boundaries for core application logic, execution contexts, platform-specific [runtime adapters](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/runtime-adapters/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](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/core-engine/presets-and-builds), mapping fine-grained export subpaths across utilities, helpers, middleware, and adapters. Sources: [package.json:119-276](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/package.json#L119-L276), [jsr.json:1-106](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/jsr.json#L1-L106) ## 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`. ```json { "name": "@hono/hono", "version": "0.0.0", "compilerOptions": { "lib": ["dom", "dom.iterable", "deno.ns"] }, "unstable": ["sloppy-imports"] } ``` Sources: [jsr.json:1-110](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/jsr.json#L1-L110) > [!NOTE] > The JSR configuration directly references source TypeScript files within `src/` as entrypoints, whereas the npm distribution targets compiled output artifacts located under `dist/`. ### 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/`. | Subpath Identifier | JSR Source Target | npm Import Target | npm Require Target | | :--- | :--- | :--- | :--- | | `.` | `./src/index.ts` | `./dist/index.js` | `./dist/cjs/index.js` | | `./tiny` | `./src/preset/tiny.ts` | `./dist/preset/tiny.js` | `./dist/cjs/preset/tiny.js` | | `./quick` | `./src/preset/quick.ts` | `./dist/preset/quick.js` | `./dist/cjs/preset/quick.js` | | `./router` | `./src/router.ts` | `./dist/router.js` | `./dist/cjs/router.js` | | `./client` | `./src/client/index.ts` | `./dist/client/index.js` | `./dist/cjs/client/index.js` | Sources: [jsr.json:8-106](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/jsr.json#L8-L106), [package.json:119-276](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/package.json#L119-L276) > [!WARNING] > Modifying root export paths requires synchronized updates across both `jsr.json` and `package.json` to prevent broken module resolution in either the npm or JSR distribution channels. ### 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`. ```json { "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](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/tsconfig.spec.json#L1-L11) ## 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. ```typescript import { 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](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/index.ts#L17-L53) > [!NOTE] > `src/index.ts` serves as the root public API facade for consumers importing from the main package specifier, cleanly separating engine internals from public type definitions and helper interfaces. ### 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/`. | Export Subpath | Source Module Target | Core Domain | | :--- | :--- | :--- | | `./cors` | `./src/middleware/cors/index.ts` | Middleware | | `./csrf` | `./src/middleware/csrf/index.ts` | Middleware | | `./jwt` | `./src/middleware/jwt/index.ts` | Middleware | | `./etag` | `./src/middleware/etag/index.ts` | Middleware | | `./logger` | `./src/middleware/logger/index.ts` | Middleware | | `./request-id` | `./src/middleware/request-id/index.ts` | [Request ID and Language](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/traffic-middleware/request-id-and-language) | | `./language` | `./src/middleware/language/index.ts` | [Request ID and Language](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/traffic-middleware/request-id-and-language) | | `./ssg` | `./src/helper/ssg/index.ts` | [Static Site Generation](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/helpers-and-tooling/static-site-generation) | Sources: [package.json:123-272](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/package.json#L123-L272) ## 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](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/router/reg-exp-router/index.ts#L1-L7) ### 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](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/router/reg-exp-router/index.ts#L6-L7) > [!TIP] > Use `PreparedRegExpRouter` alongside `buildInitParams` and `serializeInitParams` when pre-compiling regular expression routing tables to bypass runtime regex construction overhead in cold-start environments. ### 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](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/router/trie-router/index.ts#L1-L6), [src/router/smart-router/index.ts:1-6](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/router/smart-router/index.ts#L1-L6), [src/router/linear-router/index.ts:1-6](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/router/linear-router/index.ts#L1-L6) > [!NOTE] > `SmartRouter` inspects registered routes at initialization time to automatically select the optimal underlying router implementation based on pattern complexity. ## 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. ```typescript export const handle = ( app: Hono ): PagesFunction => (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](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/adapter/cloudflare-pages/handler.ts#L32-L46) > [!NOTE] > `handleMiddleware` in the Cloudflare Pages adapter constructs a Hono `Context` with an expanded environment object containing the full [execution context](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/core-engine/execution-context), wrapping incoming `next()` calls and catching `HTTPException` instances to format native `Response` outputs. 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. ```typescript export 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](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/adapter/cloudflare-pages/handler.ts#L114-L123) ### Connection Metadata and Target Exports Netlify deployment integration exports its request handler and connection information resolver through a unified adapter entry point module. | Adapter Module | Source Path | Exported Symbols | Target Environment | | :--- | :--- | :--- | :--- | | `netlify` | `src/adapter/netlify/mod.ts` | `handle`, `getConnInfo` | Netlify Functions / Edge | | `cloudflare-pages` | `src/adapter/cloudflare-pages/handler.ts` | `handle`, `handleMiddleware`, `serveStatic` | Cloudflare Pages | Sources: [src/adapter/netlify/mod.ts:1-2](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/adapter/netlify/mod.ts#L1-L2), [src/adapter/cloudflare-pages/handler.ts:32-123](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/adapter/cloudflare-pages/handler.ts#L32-L123) > [!TIP] > Platform-specific adapters keep framework core logic decoupled from vendor request types by normalizing incoming platform events directly into standard `Request` objects before handing execution over to Hono. ## 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`. ```typescript export { 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](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/jsx/dom/jsx-runtime.ts#L6-L8) > [!NOTE] > The `hono/jsx/dom/jsx-runtime` module re-exports `jsxDEV` under both `jsx` and `jsxs` identifiers alongside `Fragment` and the `JSX` type definitions to satisfy compiler transform requirements for interactive client components. ### Subtree Package Exports Export definitions in `package.json` expose specialized subpath entries for server-side JSX helpers, streaming renderers, and client-side DOM bundles. | Subpath Entry | Types Declaration | ESM Import Target | CommonJS Require Target | | :--- | :--- | :--- | :--- | | `./jsx` | `./dist/types/jsx/index.d.ts` | `./dist/jsx/index.js` | `./dist/cjs/jsx/index.js` | | `./jsx/jsx-runtime` | `./dist/types/jsx/jsx-runtime.d.ts` | `./dist/jsx/jsx-runtime.js` | `./dist/cjs/jsx/jsx-runtime.js` | | `./jsx/streaming` | `./dist/types/jsx/streaming.d.ts` | `./dist/jsx/streaming.js` | `./dist/cjs/jsx/streaming.js` | | `./jsx/dom` | `./dist/types/jsx/dom/index.d.ts` | `./dist/jsx/dom/index.js` | `./dist/cjs/jsx/dom/index.js` | | `./jsx/dom/jsx-runtime` | `./dist/types/jsx/dom/jsx-runtime.d.ts` | `./dist/jsx/dom/jsx-runtime.js` | `./dist/cjs/jsx/dom/jsx-runtime.js` | | `./jsx/dom/client` | `./dist/types/jsx/dom/client.d.ts` | `./dist/jsx/dom/client.js` | `./dist/cjs/jsx/dom/client.js` | | `./jsx/dom/css` | `./dist/types/jsx/dom/css.d.ts` | `./dist/jsx/dom/css.js` | `./dist/cjs/jsx/dom/css.js` | | `./jsx/dom/server` | `./dist/types/jsx/dom/server.d.ts` | `./dist/jsx/dom/server.js` | `./dist/cjs/jsx/dom/server.js` | Sources: [package.json:153-207](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/package.json#L153-L207) > [!TIP] > Use hono/jsx/dom/client when mounting interactive component trees on browser targets, while keeping server-rendered templates decoupled by utilizing hono/jsx or hono/jsx-renderer. ## Related - [Overview](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/getting-started/overview) - [Presets and Builds](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/core-engine/presets-and-builds) ## Sitemap See the full [sitemap](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/llms.txt) for all pages in this wiki.