--- title: "Project Structure" description: "Hono is architected as a lightweight, modular web framework that prioritizes web standards. The project structure is carefully designed to facilitate multi-platform compatibility, including runtime..." last_updated: "2026-07-02T09:13:47.265272+00:00" canonical_url: "https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/orientation-arc/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/main/package.json) - [jsr.json](https://github.com/blade47/hono/blob/main/jsr.json) - [src/adapter/cloudflare-pages/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts) - [src/jsx/hooks/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/hooks/index.ts) - [src/jsx/base.ts](https://github.com/blade47/hono/blob/main/src/jsx/base.ts) - [src/jsx/context.ts](https://github.com/blade47/hono/blob/main/src/jsx/context.ts) - [src/middleware/jsx-renderer/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/jsx-renderer/index.ts) - [src/helper/ssg/ssg.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts) - [src/jsx/jsx-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-runtime.ts) - [src/jsx/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/index.ts) - [vitest.config.ts](https://github.com/blade47/hono/blob/main/vitest.config.ts) - [src/middleware/language/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/language/index.ts) - [src/adapter/cloudflare-pages/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/index.ts) - [src/router.ts](https://github.com/blade47/hono/blob/main/src/router.ts) - [src/helper/factory/index.ts](https://github.com/blade47/hono/blob/main/src/helper/factory/index.ts) - [src/middleware/jwt/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/jwt/index.ts) - [src/adapter/netlify/mod.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/mod.ts) - [src/helper/ssg/index.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/index.ts) - [src/adapter/netlify/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/index.ts) - [src/jsx/dom/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/index.ts) - [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
Hono is architected as a lightweight, modular web framework that prioritizes web standards. The project structure is carefully designed to facilitate multi-platform compatibility, including runtimes like Node.js, Bun, Deno, Cloudflare Workers, and serverless environments. By keeping the core logic decoupled from environment-specific APIs, Hono ensures consistent behavior across these diverse deployment targets while remaining highly performant. The hierarchy is organized into specific domain folders: `src/` serves as the primary root containing the core logic, which is further sub-divided into functional subsystems like `jsx/` for templating, `middleware/` for request/response processing, `helper/` for utility operations, and `adapter/` for platform-specific glue code. This modularity allows for tree-shaking and efficient code distribution, enabling users to import only the components they require. This wiki details the internal structure and organization of these components, tracing how Hono wires together its routing engine, rendering pipeline, and middleware chains to deliver a unified interface across different environments. ## Core Package Configuration The project is configured via `package.json` and `jsr.json`. These files define the external API surface area, controlling how the library is exported to consumers. By utilizing granular `exports` fields, the framework allows developers to import specific sub-packages (e.g., `hono/jsx`, `hono/jwt`, `hono/adapter/cloudflare-pages`), reducing the bundle size significantly. | Configuration File | Primary Purpose | | :--- | :--- | | `package.json` | Project metadata, build scripts, and ESM/CJS exports mapping. | | `jsr.json` | Configuration for JSR registry, defining public modules and export paths. | Sources: [package.json:1-701](https://github.com/blade47/hono/blob/main/package.json#L1-L701), [jsr.json:1-111](https://github.com/blade47/hono/blob/main/jsr.json#L1-L111) ## Adapter Architecture Adapters act as the translation layer between Hono's `fetch`-compliant core and the native request/response objects provided by specific platforms. Each adapter lives in `src/adapter/` and provides a standard interface (typically a `handle` function) that transforms platform-specific events into a standard `Request` object. > [!NOTE] > The Cloudflare Pages adapter provides both a standard `handle` for worker-style routing and a `handleMiddleware` wrapper to allow Hono middleware to interact with `EventContext` bindings directly. Sources: [src/adapter/cloudflare-pages/handler.ts:32-46](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts#L32-L46), [src/adapter/cloudflare-pages/handler.ts:49-102](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts#L49-L102) ## JSX Rendering Pipeline The JSX subsystem (`src/jsx/`) is a comprehensive template rendering engine supporting both static string generation and DOM-based client-side rendering. It includes intrinsic element support, context management, and hooks (`src/jsx/hooks/index.ts`). Hooks such as `useState` manage component-local state by maintaining a persistent hook index tracked during the rendering cycle within the context stack. This ensures that state is scoped to the specific component instance during the node tree build process. Sources: [src/jsx/hooks/index.ts:182-243](https://github.com/blade47/hono/blob/main/src/jsx/hooks/index.ts#L182-L243) ## Routing Engine Routing in Hono is handled by a dispatchable router interface. The `src/router.ts` defines the contract for routers. The system supports multiple router strategies (RegExp, Trie, Linear, Pattern) to allow for performance tuning depending on the complexity of the route configuration. The dispatcher returns an array of handler-parameter mappings, which are interpreted by the core `Hono` engine to resolve execution flow based on the method and path provided by the incoming `Request`. Sources: [src/router.ts:25-52](https://github.com/blade47/hono/blob/main/src/router.ts#L25-L52) ## Middleware and Factory Patterns Hono uses a factory-based approach to middleware initialization. The `src/helper/factory/` module provides a way to define middleware and handlers with strict type-safety, which is crucial given the complex intersection types generated by Hono's route builder. ```mermaid flowchart TD App[Hono Application] --> Factory[Factory Helper] Factory --> MW[Middleware Logic] Factory --> Hndlr[Handlers] MW --> Context[Context Propagation] ``` Sources: [src/helper/factory/index.ts:332-366](https://github.com/blade47/hono/blob/main/src/helper/factory/index.ts#L332-L366) ## Static Site Generation (SSG) Mechanism The SSG helper in `src/helper/ssg/` provides a programmatic interface to crawl the Hono app and generate static files. The process involves a `pool` of concurrent requests that hit the app's `fetch` method, collecting the response content and determining the output path based on the MIME type. The resolution of the output file extension is governed by `determineExtension`: 1. Check against the user-provided mapping (provided via `options.extensionMap`). 2. Fallback to `getExtension` (via `src/utils/mime`). 3. Default to `.html` if no MIME match is found. Sources: [src/helper/ssg/ssg.ts:99-108](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts#L99-L108) ## Design Trade-offs The current codebase reflects several deliberate architectural choices: | Design Choice | Benefit | Cost | | :--- | :--- | :--- | | Middleware-on-Request | High flexibility and request-lifecycle control | Complex type-level definitions | | Adapter-based Core | Ubiquitous runtime compatibility | Increased maintenance surface for platform-specific edge cases | | Factory Helpers | Strong type inference in handlers | Verbose boilerplate in setup | Sources: [src/helper/factory/index.ts:332-366](https://github.com/blade47/hono/blob/main/src/helper/factory/index.ts#L332-L366), [src/adapter/cloudflare-pages/handler.ts:32-46](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts#L32-L46) ## Related - [Overview](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/orientation-arc/overview) - [Quick Start](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/orientation-arc/quick-start) ## Sitemap See the full [sitemap](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/llms.txt) for all pages in this wiki.