---
title: "Quick Start"
description: "Hono is a web framework built fundamentally on Web Standards, designed for environments like Cloudflare Workers, Deno, Bun, and traditional Node.js/Lambda runtimes. The \"Quick Start\" capabilities r..."
last_updated: "2026-07-02T09:13:47.223584+00:00"
canonical_url: "https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/orientation-arc/quick-start"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [package.json](https://github.com/blade47/hono/blob/main/package.json)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/preset/quick.ts](https://github.com/blade47/hono/blob/main/src/preset/quick.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/hono.ts](https://github.com/blade47/hono/blob/main/src/hono.ts)
- [src/adapter/cloudflare-pages/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts)
- [src/adapter/lambda-edge/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/lambda-edge/handler.ts)
- [src/helper/proxy/index.ts](https://github.com/blade47/hono/blob/main/src/helper/proxy/index.ts)
- [src/preset/tiny.ts](https://github.com/blade47/hono/blob/main/src/preset/tiny.ts)
- [src/index.ts](https://github.com/blade47/hono/blob/main/src/index.ts)
- [runtime-tests/workerd/index.ts](https://github.com/blade47/hono/blob/main/runtime-tests/workerd/index.ts)
- [src/adapter/vercel/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/vercel/handler.ts)
- [src/adapter/netlify/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/handler.ts)
- [src/helper/dev/index.ts](https://github.com/blade47/hono/blob/main/src/helper/dev/index.ts)
- [src/router/linear-router/index.ts](https://github.com/blade47/hono/blob/main/src/router/linear-router/index.ts)
- [src/adapter/cloudflare-pages/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/index.ts)
- [src/adapter/vercel/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/vercel/index.ts)
- [src/adapter/service-worker/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/service-worker/index.ts)
- [src/router/smart-router/index.ts](https://github.com/blade47/hono/blob/main/src/router/smart-router/index.ts)
- [src/adapter/deno/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/deno/index.ts)
- [src/adapter/cloudflare-workers/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-workers/index.ts)
- [jsr.json](https://github.com/blade47/hono/blob/main/jsr.json)
- [src/adapter/aws-lambda/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/index.ts)
- [src/adapter/lambda-edge/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/lambda-edge/index.ts)
- [src/router/pattern-router/index.ts](https://github.com/blade47/hono/blob/main/src/router/pattern-router/index.ts)
- [src/helper/testing/index.ts](https://github.com/blade47/hono/blob/main/src/helper/testing/index.ts)
- [src/adapter/service-worker/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/service-worker/handler.ts)
- [src/adapter/bun/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/bun/index.ts)
- [src/adapter/netlify/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/index.ts)
</details>

Hono is a web framework built fundamentally on Web Standards, designed for environments like Cloudflare Workers, Deno, Bun, and traditional Node.js/Lambda runtimes. The "Quick Start" capabilities reflect the framework's core design philosophy: to provide a lightweight, high-performance router and execution context that remains agnostic to the underlying platform.

The system achieves this by decoupling the core router implementation from the request handling logic. The `Hono` class provides the common interface for routing and middleware, while different presets allow developers to trade off binary size against routing complexity.

When starting a project, a developer interacts with the `Hono` instance, which serves as the entry point. The framework maps HTTP methods to internal route tables and provides a standardized `Context` object that encapsulates the environment, request, and lifecycle methods, ensuring that code remains portable across disparate edge and serverless providers.

## Core Initialization Mechanics

At the heart of the system, initialization occurs by constructing an `Hono` instance. The constructor accepts an optional configuration object, which allows for defining the routing strategy, strict path matching, and path normalization logic.

```typescript
// Example: Standard Quick Start initialization
import { Hono } from 'hono'
const app = new Hono()

app.get('/', (c) => c.text('Hono!'))

export default app
```
Sources: [src/index.ts:6-14](https://github.com/blade47/hono/blob/main/src/index.ts#L6-L14)

The constructor delegates to the `Hono` class, which handles the registration of HTTP methods (GET, POST, etc.) into an internal routing table using internal registration methods that populate the router.

> [!NOTE]
> The `Hono` class is the primary interface. It initializes with a default router (e.g., `SmartRouter`), while specific preset files inject different routing implementations to optimize for performance or bundle size.

Sources: [src/hono.ts:26-34](https://github.com/blade47/hono/blob/main/src/hono.ts#L26-L34), [src/preset/tiny.ts:16-20](https://github.com/blade47/hono/blob/main/src/preset/tiny.ts#L16-L20)

## Routing Architecture

Routing is the core mechanism that determines how an incoming `Request` object maps to a `Handler`. Hono utilizes a routing system based on registered patterns.

| Router Type | Implementation File | Strategy |
| :--- | :--- | :--- |
| `SmartRouter` | `src/router/smart-router/` | Adaptive; delegates to other routers based on pattern complexity. |
| `RegExpRouter` | `src/router/reg-exp-router/` | Uses regular expressions for matching dynamic paths. |
| `TrieRouter` | `src/router/trie-router/` | Uses a trie data structure for performant prefix matching. |
| `PatternRouter` | `src/router/pattern-router/` | Optimized for small, simple route definitions. |
| `LinearRouter` | `src/router/linear-router/` | Simple linear search; efficient for very few routes. |

Sources: [src/hono.ts:3-5](https://github.com/blade47/hono/blob/main/src/hono.ts#L3-L5), [src/preset/quick.ts:8-10](https://github.com/blade47/hono/blob/main/src/preset/quick.ts#L8-L10)

The routing mechanism is triggered when a request is dispatched, which takes a request and environment variables, retrieves the path, and performs a lookup to match the method and path against the internal router's index.

Sources: [src/hono-base.ts:418-419](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L418-L419)

## The Request Dispatch Flow

When a request arrives, the `fetch` method serves as the entry point. The following chain shows how the request is processed:

1. `fetch()` → Entry point; receives the raw `Request` and environment objects.
2. `dispatch` logic → Prepares the `Context` and performs route matching.
3. `router.match()` → Performs lookups to find eligible handlers.
4. `compose()` → Executes the middleware and handler stack if more than one handler is registered.

If a single handler is found, the dispatch path avoids `compose` to optimize performance, calling the handler directly and resolving its promise.

```mermaid
flowchart TD
    A[fetch] --> B["dispatch logic"]
    B --> C["router.match"]
    C --> D{Single<br>Handler?}
    D -- Yes --> E["Direct Execute"]
    D -- No --> F["compose(handlers)"]
    E --> G[Context Finalized]
    F --> G
```
Sources: [src/hono-base.ts:429-450](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L429-L450)

## The Context Object (`Context<E>`)

The `Context` object is a load-bearing structure. It is created per-request and provides the interface through which developers interact with the request data and define the response.

Key components of `Context`:
- `env`: The environment-specific bindings (e.g., KV, D1, or environment variables).
- `req`: A wrapper around the native `Request` providing helper methods.
- `res`: The response container. When set, it marks the context as `finalized`.
- `set()` / `get()`: A shared storage mechanism for variables across middleware layers.

> [!IMPORTANT]
> The `Context` object handles the logic of finalizing the response. If the `finalized` flag is false after the middleware stack completes, the framework throws an error to ensure that the developer has provided a valid response object.

Sources: [src/context.ts:300-345](https://github.com/blade47/hono/blob/main/src/context.ts#L300-L345), [src/hono-base.ts:455-459](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L455-L459)

## Adapter Logic

Hono is built to run everywhere. The adapter pattern bridges the gap between different cloud runtime event structures (like AWS API Gateway, Cloudflare Pages, or Vercel functions) and the internal `Hono.fetch` method.

| Adapter | Primary Entry Point | Strategy |
| :--- | :--- | :--- |
| `aws-lambda` | `handle()` | Converts Lambda event structures (APIGateway, ALB) to Request. |
| `cloudflare-pages` | `handle()` | Maps `EventContext` properties to the `hono` lifecycle. |
| `lambda-edge` | `handle()` | Translates `CloudFrontRequest` for CloudFront edge events. |
| `bun` | `getBunServer()` | Native integration for Bun's HTTP server. |

Sources: [src/adapter/aws-lambda/handler.ts:239-252](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L239-L252), [src/adapter/cloudflare-pages/handler.ts:32-46](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts#L32-L46)

Each adapter implements its own handling logic. For instance, the `aws-lambda` adapter includes logic for determining if a response should be base64-encoded, which is a common requirement in API Gateway event handling.

## Development and Testing

The system includes robust helpers for development and testing. `showRoutes` provides an observability tool to inspect the route table, while `testClient` allows developers to test their applications without performing network-level I/O.

```typescript
// Example: Testing with testClient
import { Hono } from 'hono'
import { testClient } from 'hono/testing'

const app = new Hono()
app.get('/test', (c) => c.json({ data: 'ok' }))

const client = testClient(app)
const res = await client.test.$get()
const data = await res.json() // { data: 'ok' }
```
Sources: [src/helper/testing/index.ts:16-27](https://github.com/blade47/hono/blob/main/src/helper/testing/index.ts#L16-L27)

`testClient` works by injecting a custom `fetch` function that points directly to the `app.request` internal method, bypassing the need for an actual server.

Sources: [src/helper/testing/index.ts:22-24](https://github.com/blade47/hono/blob/main/src/helper/testing/index.ts#L22-L24)

## Related

- [Overview](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/orientation-arc/overview)
- [Project Structure](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/orientation-arc/project-structure)


## Sitemap

See the full [sitemap](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/llms.txt) for all pages in this wiki.