{content}
+ + + ); + }); + await next(); +}); +``` + +Then, you can utilize `c.render()` to create responses within this layout. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/", (c) => { + return c.render("Hello!"); +}); +``` + +The output of which will be: + +```html + + +Hello!
+ + +``` + +Additionally, this feature offers the flexibility to customize arguments. +To ensure type safety, types can be defined as: + +```ts +declare module "hono" { + type ContextRenderer = { + ( + content: string | Promise{content}
+ + + ) + }) + await next() +}) + +app.get('/pages/my-favorite', (c) => { + return c.render(Ramen and Sushi
, { + title: 'My favorite', + }) +}) + +app.get('/pages/my-hobbies', (c) => { + return c.render(Watching baseball
, { + title: 'My hobbies', + }) +}) +``` + +## executionCtx + +You can access Cloudflare Workers' specific [ExecutionContext](https://developers.cloudflare.com/workers/runtime-apis/context/). + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono<{ + Bindings: { + KV: any; + }; +}>(); +declare const key: string; +declare const data: string; +// ---cut--- +// ExecutionContext object +app.get("/foo", async (c) => { + c.executionCtx.waitUntil(c.env.KV.put(key, data)); + // ... +}); +``` + +## event + +You can access Cloudflare Workers' specific `FetchEvent`. This was used in "Service Worker" syntax. But, it is not recommended now. + +```ts twoslash +import { Hono } from "hono"; +declare const key: string; +declare const data: string; +type KVNamespace = any; +// ---cut--- +// Type definition to make type inference +type Bindings = { + MY_KV: KVNamespace; +}; + +const app = new Hono<{ Bindings: Bindings }>(); + +// FetchEvent object (only set when using Service Worker syntax) +app.get("/foo", async (c) => { + c.event.waitUntil(c.env.MY_KV.put(key, data)); + // ... +}); +``` + +## env + +In Cloudflare Workers Environment variables, secrets, KV namespaces, D1 database, R2 bucket etc. that are bound to a worker are known as bindings. +Regardless of type, bindings are always available as global variables and can be accessed via the context `c.env.BINDING_KEY`. + +```ts twoslash +import { Hono } from "hono"; +type KVNamespace = any; +// ---cut--- +// Type definition to make type inference +type Bindings = { + MY_KV: KVNamespace; +}; + +const app = new Hono<{ Bindings: Bindings }>(); + +// Environment object for Cloudflare Workers +app.get("/", async (c) => { + c.env.MY_KV.get("my-key"); + // ... +}); +``` + +## error + +If the Handler throws an error, the error object is placed in `c.error`. +You can access it in your middleware. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.use(async (c, next) => { + await next(); + if (c.error) { + // do something... + } +}); +``` + +## ContextVariableMap + +For instance, if you wish to add type definitions to variables when a specific middleware is used, you can extend `ContextVariableMap`. For example: + +```ts +declare module "hono" { + type ContextVariableMap = { + result: string; + }; +} +``` + +You can then utilize this in your middleware: + +```ts twoslash +import { createMiddleware } from "hono/factory"; +// ---cut--- +const mw = createMiddleware(async (c, next) => { + c.set("result", "some values"); // result is a string + await next(); +}); +``` + +In a handler, the variable is inferred as the proper type: + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono<{ Variables: { result: string } }>(); +// ---cut--- +app.get("/", (c) => { + const val = c.get("result"); // val is a string + // ... + return c.json({ result: val }); +}); +``` diff --git a/.cursor/rules/hono/api/exception.mdc b/.cursor/rules/hono/api/exception.mdc new file mode 100644 index 0000000..a7b0e97 --- /dev/null +++ b/.cursor/rules/hono/api/exception.mdc @@ -0,0 +1,92 @@ +--- +description: Hono Exception API reference for error handling, HTTP exceptions, and custom error responses in web applications +globs: +alwaysApply: false +--- + +# Exception + +When a fatal error occurs, such as authentication failure, an HTTPException must be thrown. + +## throw HTTPException + +This example throws an HTTPException from the middleware. + +```ts twoslash +import { Hono } from "hono"; +// ---cut--- +import { HTTPException } from "hono/http-exception"; +const app = new Hono(); +declare const authorized: boolean; + +// ... + +app.post("/auth", async (c, next) => { + // authentication + if (authorized === false) { + throw new HTTPException(401, { message: "Custom error message" }); + } + await next(); +}); +``` + +You can specify the response to be returned back to the user. + +```ts twoslash +import { HTTPException } from "hono/http-exception"; + +const errorResponse = new Response("Unauthorized", { + status: 401, + headers: { + Authenticate: "error=\"invalid_token\"", + }, +}); + +throw new HTTPException(401, { res: errorResponse }); +``` + +## Handling HTTPException + +You can handle the thrown HTTPException with `app.onError`. + +```ts twoslash +import { Hono } from "hono"; +// ---cut--- +import { HTTPException } from "hono/http-exception"; +const app = new Hono(); + +// ... + +app.onError((err, c) => { + if (err instanceof HTTPException) { + // Get the custom response + return err.getResponse(); + } + // ... + // ---cut-start--- + return c.text("Error"); + // ---cut-end--- +}); +``` + +## `cause` + +The `cause` option is available to add a [`cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) data. + +```ts twoslash +import { Context, Hono } from "hono"; +import { HTTPException } from "hono/http-exception"; +const app = new Hono(); +declare const message: string; +declare const authorize: (c: Context) => void; +// ---cut--- +app.post("/auth", async (c, next) => { + try { + authorize(c); + } + catch (e) { + throw new HTTPException(401, { message, cause: e }); + } + await next(); +}); +``` diff --git a/.cursor/rules/hono/api/hono.mdc b/.cursor/rules/hono/api/hono.mdc new file mode 100644 index 0000000..8cf60cd --- /dev/null +++ b/.cursor/rules/hono/api/hono.mdc @@ -0,0 +1,234 @@ +--- +description: Hono core API reference covering the main Hono class, application setup, routing methods, and configuration options +globs: +alwaysApply: false +--- + +# App - Hono + +`Hono` is the primary object. +It will be imported first and used until the end. + +```ts twoslash +import { Hono } from "hono"; + +const app = new Hono(); +// ... + +export default app; // for Cloudflare Workers or Bun +``` + +## Methods + +An instance of `Hono` has the following methods. + +- app.**HTTP_METHOD**(\[path,\]handler|middleware...) +- app.**all**(\[path,\]handler|middleware...) +- app.**on**(method|method[], path|path[], handler|middleware...) +- app.**use**(\[path,\]middleware) +- app.**route**(path, \[app\]) +- app.**basePath**(path) +- app.**notFound**(handler) +- app.**onError**(err, handler) +- app.**mount**(path, anotherApp) +- app.**fire**() +- app.**fetch**(request, env, event) +- app.**request**(path, options) + +The first part of them is used for routing, please refer to the [routing section](/docs/api/routing). + +## Not Found + +`app.notFound` allows you to customize a Not Found Response. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.notFound((c) => { + return c.text("Custom 404 Message", 404); +}); +``` + +## Error Handling + +`app.onError` handles an error and returns a customized Response. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.onError((err, c) => { + console.error(`${err}`); + return c.text("Custom Error Message", 500); +}); +``` + +## fire() + +`app.fire()` automatically adds a global `fetch` event listener. + +This can be useful for environments that adhere to the [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API), such as [non-ES module Cloudflare Workers](https://developers.cloudflare.com/workers/reference/migrate-to-module-workers/). + +`app.fire()` executes the following for you: + +```ts +addEventListener('fetch', (event: FetchEventLike): void => { + event.respondWith(this.dispatch(...)) +}) +``` + +## fetch() + +`app.fetch` will be entry point of your application. + +For Cloudflare Workers, you can use the following: + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +type Env = any; +type ExecutionContext = any; +// ---cut--- +export default { + fetch(request: Request, env: Env, ctx: ExecutionContext) { + return app.fetch(request, env, ctx); + }, +}; +``` + +or just do: + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +export default app; +``` + +Bun: + + +```ts +export default app; // [!code --] +export default { // [!code ++] + port: 3000, // [!code ++] + fetch: app.fetch, // [!code ++] +}; // [!code ++] +``` + +## request() + +`request` is a useful method for testing. + +You can pass a URL or pathname to send a GET request. +`app` will return a `Response` object. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +declare const test: (name: string, fn: () => void) => void; +declare const expect: (value: any) => any; +// ---cut--- +test("GET /hello is ok", async () => { + const res = await app.request("/hello"); + expect(res.status).toBe(200); +}); +``` + +You can also pass a `Request` object: + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +declare const test: (name: string, fn: () => void) => void; +declare const expect: (value: any) => any; +// ---cut--- +test("POST /message is ok", async () => { + const req = new Request("Hello!", { + method: "POST", + }); + const res = await app.request(req); + expect(res.status).toBe(201); +}); +``` + +## mount() + +The `mount()` allows you to mount applications built with other frameworks into your Hono application. + +```ts +import { Hono } from "hono"; +import { Router as IttyRouter } from "itty-router"; + +// Create itty-router application +const ittyRouter = IttyRouter(); + +// Handle `GET /itty-router/hello` +ittyRouter.get("/hello", () => new Response("Hello from itty-router")); + +// Hono application +const app = new Hono(); + +// Mount! +app.mount("/itty-router", ittyRouter.handle); +``` + +## strict mode + +Strict mode defaults to `true` and distinguishes the following routes. + +- `/hello` +- `/hello/` + +`app.get('/hello')` will not match `GET /hello/`. + +By setting strict mode to `false`, both paths will be treated equally. + +```ts twoslash +import { Hono } from "hono"; +// ---cut--- +const app = new Hono({ strict: false }); +``` + +## router option + +The `router` option specifices which router to use. The default router is `SmartRouter`. If you want to use `RegExpRouter`, pass it to a new `Hono` instance: + +```ts twoslash +import { Hono } from "hono"; +// ---cut--- +import { RegExpRouter } from "hono/router/reg-exp-router"; + +const app = new Hono({ router: new RegExpRouter() }); +``` + +## Generics + +You can pass Generics to specify the types of Cloudflare Workers Bindings and variables used in `c.set`/`c.get`. + +```ts twoslash +import { Hono } from "hono"; +type User = any; +declare const user: User; +// ---cut--- +type Bindings = { + TOKEN: string; +}; + +type Variables = { + user: User; +}; + +const app = new Hono<{ + Bindings: Bindings; + Variables: Variables; +}>(); + +app.use("/auth/*", async (c, next) => { + const token = c.env.TOKEN; // token is `string` + // ... + c.set("user", user); // user should be `User` + await next(); +}); +``` diff --git a/.cursor/rules/hono/api/index.mdc b/.cursor/rules/hono/api/index.mdc new file mode 100644 index 0000000..df24965 --- /dev/null +++ b/.cursor/rules/hono/api/index.mdc @@ -0,0 +1,18 @@ +--- +description: Hono API reference index providing overview of core APIs, classes, and methods available in the framework +globs: +alwaysApply: false +--- + +# API + +Hono's API is simple. +Just composed by extended objects from Web Standards. +So, you can understand it well quickly. + +In this section, we introduce API of Hono like below. + +- Hono object +- About routing +- Context object +- About middleware diff --git a/.cursor/rules/hono/api/presets.mdc b/.cursor/rules/hono/api/presets.mdc new file mode 100644 index 0000000..0b814b1 --- /dev/null +++ b/.cursor/rules/hono/api/presets.mdc @@ -0,0 +1,68 @@ +--- +description: Hono presets API reference for pre-configured application setups and optimized builds for different deployment targets +globs: +alwaysApply: false +--- + +# Presets + +Hono has several routers, each designed for a specific purpose. +You can specify the router you want to use in the constructor of Hono. + +**Presets** are provided for common use cases, so you don't have to specify the router each time. +The `Hono` class imported from all presets is the same, the only difference being the router. +Therefore, you can use them interchangeably. + +## `hono` + +Usage: + +```ts twoslash +import { Hono } from "hono"; +``` + +Routers: + +```ts +this.router = new SmartRouter({ + routers: [new RegExpRouter(), new TrieRouter()], +}); +``` + +## `hono/quick` + +Usage: + +```ts twoslash +import { Hono } from "hono/quick"; +``` + +Router: + +```ts +this.router = new SmartRouter({ + routers: [new LinearRouter(), new TrieRouter()], +}); +``` + +## `hono/tiny` + +Usage: + +```ts twoslash +import { Hono } from "hono/tiny"; +``` + +Router: + +```ts +this.router = new PatternRouter(); +``` + +## Which preset should I use? + +| Preset | Suitable platforms | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `hono` | This is highly recommended for most use cases. Although the registration phase may be slower than `hono/quick`, it exhibits high performance once booted. It's ideal for long-life servers built with **Deno**, **Bun**, or **Node.js**. For environments such as **Cloudflare Workers**, **Deno Deploy**, where v8 isolates are utilized, this preset is suitable as well. Because the isolations persist for a certain amount of time after booting. | +| `hono/quick` | This preset is designed for environments where the application is initialized for every request. **Fastly Compute** operates in this manner, thus this preset is recommended for such use. | +| `hono/tiny` | This is the smallest router package and it's suitable for environments where resources are limited. | diff --git a/.cursor/rules/hono/api/request.mdc b/.cursor/rules/hono/api/request.mdc new file mode 100644 index 0000000..806a96b --- /dev/null +++ b/.cursor/rules/hono/api/request.mdc @@ -0,0 +1,375 @@ +--- +description: Hono Request API reference for handling HTTP requests, parsing parameters, headers, and request body data +globs: +alwaysApply: false +--- + +# HonoRequest + +The `HonoRequest` is an object that can be taken from `c.req` which wraps a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. + +## param() + +Get the values of path parameters. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +// Captured params +app.get("/entry/:id", async (c) => { + const id = c.req.param("id"); + // ^? + // ... +}); + +// Get all params at once +app.get("/entry/:id/comment/:commentId", async (c) => { + const { id, commentId } = c.req.param(); + // ^? +}); +``` + +## query() + +Get querystring parameters. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +// Query params +app.get("/search", async (c) => { + const query = c.req.query("q"); + // ^? +}); + +// Get all params at once +app.get("/search", async (c) => { + const { q, limit, offset } = c.req.query(); + // ^? +}); +``` + +## queries() + +Get multiple querystring parameter values, e.g. `/search?tags=A&tags=B` + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/search", async (c) => { + // tags will be string[] + const tags = c.req.queries("tags"); + // ^? + // ... +}); +``` + +## header() + +Get the request header value. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/", (c) => { + const userAgent = c.req.header("User-Agent"); + // ^? + return c.text(`Your user agent is ${userAgent}`); +}); +``` + +::: warning +When `c.req.header()` is called with no arguments, all keys in the returned record are **lowercase**. + +If you want to get the value of a header with an uppercase name, +use `c.req.header(“X-Foo”)`. + +```ts +// ❌ Will not work +const headerRecord = c.req.header(); +const foo = headerRecord["X-Foo"]; + +// ✅ Will work +const foo = c.req.header("X-Foo"); +``` + +::: + +## parseBody() + +Parse Request body of type `multipart/form-data` or `application/x-www-form-urlencoded` + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.post("/entry", async (c) => { + const body = await c.req.parseBody(); + // ... +}); +``` + +`parseBody()` supports the following behaviors. + +**Single file** + +```ts twoslash +import { Context } from "hono"; +declare const c: Context; +// ---cut--- +const body = await c.req.parseBody(); +const data = body.foo; +// ^? +``` + +`body['foo']` is `(string | File)`. + +If multiple files are uploaded, the last one will be used. + +### Multiple files + +```ts twoslash +import { Context } from "hono"; +declare const c: Context; +// ---cut--- +const body = await c.req.parseBody(); +body["foo[]"]; +``` + +`body['foo[]']` is always `(string | File)[]`. + +`[]` postfix is required. + +### Multiple files or fields with same name + +If you have a input field that allows multiple `` or multiple checkboxes with the same name ``. + +```ts twoslash +import { Context } from "hono"; +declare const c: Context; +// ---cut--- +const body = await c.req.parseBody({ all: true }); +body.foo; +``` + +`all` option is disabled by default. + +- If `body['foo']` is multiple files, it will be parsed to `(string | File)[]`. +- If `body['foo']` is single file, it will be parsed to `(string | File)`. + +### Dot notation + +If you set the `dot` option `true`, the return value is structured based on the dot notation. + +Imagine receiving the following data: + +```ts twoslash +const data = new FormData(); +data.append("obj.key1", "value1"); +data.append("obj.key2", "value2"); +``` + +You can get the structured value by setting the `dot` option `true`: + +```ts twoslash +import { Context } from "hono"; +declare const c: Context; +// ---cut--- +const body = await c.req.parseBody({ dot: true }); +// body is `{ obj: { key1: 'value1', key2: 'value2' } }` +``` + +## json() + +Parses the request body of type `application/json` + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.post("/entry", async (c) => { + const body = await c.req.json(); + // ... +}); +``` + +## text() + +Parses the request body of type `text/plain` + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.post("/entry", async (c) => { + const body = await c.req.text(); + // ... +}); +``` + +## arrayBuffer() + +Parses the request body as an `ArrayBuffer` + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.post("/entry", async (c) => { + const body = await c.req.arrayBuffer(); + // ... +}); +``` + +## blob() + +Parses the request body as a `Blob`. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.post("/entry", async (c) => { + const body = await c.req.blob(); + // ... +}); +``` + +## formData() + +Parses the request body as a `FormData`. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.post("/entry", async (c) => { + const body = await c.req.formData(); + // ... +}); +``` + +## valid() + +Get the validated data. + +```ts +app.post("/posts", async (c) => { + const { title, body } = c.req.valid("form"); + // ... +}); +``` + +Available targets are below. + +- `form` +- `json` +- `query` +- `header` +- `cookie` +- `param` + +See the [Validation section](/docs/guides/validation) for usage examples. + +## routePath() + +You can retrieve the registered path within the handler like this: + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/posts/:id", (c) => { + return c.json({ path: c.req.routePath }); +}); +``` + +If you access `/posts/123`, it will return `/posts/:id`: + +```json +{ "path": "/posts/:id" } +``` + +## matchedRoutes() + +It returns matched routes within the handler, which is useful for debugging. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.use(async (c, next) => { + await next(); + c.req.matchedRoutes.forEach(({ handler, method, path }, i) => { + const name + = handler.name + || (handler.length < 2 ? "[handler]" : "[middleware]"); + console.log( + method, + " ", + path, + " ".repeat(Math.max(10 - path.length, 0)), + name, + i === c.req.routeIndex ? "<- respond from here" : "" + ); + }); +}); +``` + +## path + +The request pathname. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/about/me", async (c) => { + const pathname = c.req.path; // `/about/me` + // ... +}); +``` + +## url + +The request url strings. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/about/me", async (c) => { + const url = c.req.url; // `http://localhost:8787/about/me` + // ... +}); +``` + +## method + +The method name of the request. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/about/me", async (c) => { + const method = c.req.method; // `GET` + // ... +}); +``` + +## raw + +The raw [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. + +```ts +// For Cloudflare Workers +app.post('/', async (c) => { + const metadata = c.req.raw.cf?.hostMetadata? + // ... +}) +``` diff --git a/.cursor/rules/hono/api/routing.mdc b/.cursor/rules/hono/api/routing.mdc new file mode 100644 index 0000000..0e6b9ab --- /dev/null +++ b/.cursor/rules/hono/api/routing.mdc @@ -0,0 +1,306 @@ +--- +description: Hono Routing API reference for defining routes, path patterns, HTTP methods, and route matching in web applications +globs: +alwaysApply: false +--- + +# Routing + +Routing of Hono is flexible and intuitive. +Let's take a look. + +## Basic + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +// HTTP Methods +app.get("/", c => c.text("GET /")); +app.post("/", c => c.text("POST /")); +app.put("/", c => c.text("PUT /")); +app.delete("/", c => c.text("DELETE /")); + +// Wildcard +app.get("/wild/*/card", (c) => { + return c.text("GET /wild/*/card"); +}); + +// Any HTTP methods +app.all("/hello", c => c.text("Any Method /hello")); + +// Custom HTTP method +app.on("PURGE", "/cache", c => c.text("PURGE Method /cache")); + +// Multiple Method +app.on(["PUT", "DELETE"], "/post", c => + c.text("PUT or DELETE /post")); + +// Multiple Paths +app.on("GET", ["/hello", "/ja/hello", "/en/hello"], c => + c.text("Hello")); +``` + +## Path Parameter + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/user/:name", async (c) => { + const name = c.req.param("name"); + // ^? + // ... +}); +``` + +or all parameters at once: + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/posts/:id/comment/:comment_id", async (c) => { + const { id, comment_id } = c.req.param(); + // ^? + // ... +}); +``` + +## Optional Parameter + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +// Will match `/api/animal` and `/api/animal/:type` +app.get("/api/animal/:type?", c => c.text("Animal!")); +``` + +## Regexp + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/post/:date{[0-9]+}/:title{[a-z]+}", async (c) => { + const { date, title } = c.req.param(); + // ^? + // ... +}); +``` + +## Including slashes + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/posts/:filename{.+\\.png}", async (c) => { + // ... +}); +``` + +## Chained route + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app + .get("/endpoint", (c) => { + return c.text("GET /endpoint"); + }) + .post((c) => { + return c.text("POST /endpoint"); + }) + .delete((c) => { + return c.text("DELETE /endpoint"); + }); +``` + +## Grouping + +You can group the routes with the Hono instance and add them to the main app with the route method. + +```ts twoslash +import { Hono } from "hono"; +// ---cut--- +const book = new Hono(); + +book.get("/", c => c.text("List Books")); // GET /book +book.get("/:id", (c) => { + // GET /book/:id + const id = c.req.param("id"); + return c.text(`Get Book: ${id}`); +}); +book.post("/", c => c.text("Create Book")); // POST /book + +const app = new Hono(); +app.route("/book", book); +``` + +## Grouping without changing base + +You can also group multiple instances while keeping base. + +```ts twoslash +import { Hono } from "hono"; +// ---cut--- +const book = new Hono(); +book.get("/book", c => c.text("List Books")); // GET /book +book.post("/book", c => c.text("Create Book")); // POST /book + +const user = new Hono().basePath("/user"); +user.get("/", c => c.text("List Users")); // GET /user +user.post("/", c => c.text("Create User")); // POST /user + +const app = new Hono(); +app.route("/", book); // Handle /book +app.route("/", user); // Handle /user +``` + +## Base path + +You can specify the base path. + +```ts twoslash +import { Hono } from "hono"; +// ---cut--- +const api = new Hono().basePath("/api"); +api.get("/book", c => c.text("List Books")); // GET /api/book +``` + +## Routing with hostname + +It works fine if it includes a hostname. + +```ts twoslash +import { Hono } from "hono"; +// ---cut--- +const app = new Hono({ + getPath: req => req.url.replace(/^https?:\/([^?]+).*$/, "$1"), +}); + +app.get("/www1.example.com/hello", c => c.text("hello www1")); +app.get("/www2.example.com/hello", c => c.text("hello www2")); +``` + +## Routing with `host` Header value + +Hono can handle the `host` header value if you set the `getPath()` function in the Hono constructor. + +```ts twoslash +import { Hono } from "hono"; +// ---cut--- +const app = new Hono({ + getPath: req => + `/${ + req.headers.get("host") + }${req.url.replace(/^https?:\/\/[^/]+(\/[^?]*).*/, "$1")}`, +}); + +app.get("/www1.example.com/hello", c => c.text("hello www1")); + +// A following request will match the route: +// new Request('http://www1.example.com/hello', { +// headers: { host: 'www1.example.com' }, +// }) +``` + +By applying this, for example, you can change the routing by `User-Agent` header. + +## Routing priority + +Handlers or middleware will be executed in registration order. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/book/a", c => c.text("a")); // a +app.get("/book/:slug", c => c.text("common")); // common +``` + +``` +GET /book/a ---> `a` +GET /book/b ---> `common` +``` + +When a handler is executed, the process will be stopped. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("*", c => c.text("common")); // common +app.get("/foo", c => c.text("foo")); // foo +``` + +``` +GET /foo ---> `common` // foo will not be dispatched +``` + +If you have the middleware that you want to execute, write the code above the handler. + +```ts twoslash +import { Hono } from "hono"; +import { logger } from "hono/logger"; +const app = new Hono(); +// ---cut--- +app.use(logger()); +app.get("/foo", c => c.text("foo")); +``` + +If you want to have a "_fallback_" handler, write the code below the other handler. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.get("/bar", c => c.text("bar")); // bar +app.get("*", c => c.text("fallback")); // fallback +``` + +``` +GET /bar ---> `bar` +GET /foo ---> `fallback` +``` + +## Grouping ordering + +Note that the mistake of grouping routings is hard to notice. +The `route()` function takes the stored routing from the second argument (such as `three` or `two`) and adds it to its own (`two` or `app`) routing. + +```ts +three.get("/hi", c => c.text("hi")); +two.route("/three", three); +app.route("/two", two); + +export default app; +``` + +It will return 200 response. + +``` +GET /two/three/hi ---> `hi` +``` + +However, if they are in the wrong order, it will return a 404. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +const two = new Hono(); +const three = new Hono(); +// ---cut--- +three.get("/hi", c => c.text("hi")); +app.route("/two", two); // `two` does not have routes +two.route("/three", three); + +export default app; +``` + +``` +GET /two/three/hi ---> 404 Not Found +``` diff --git a/.cursor/rules/hono/concepts/benchmarks.mdc b/.cursor/rules/hono/concepts/benchmarks.mdc new file mode 100644 index 0000000..bf62e39 --- /dev/null +++ b/.cursor/rules/hono/concepts/benchmarks.mdc @@ -0,0 +1,177 @@ +--- +description: Hono performance benchmarks comparing speed and efficiency against other web frameworks across different JavaScript runtimes +globs: +alwaysApply: false +--- + +# Benchmarks + +Benchmarks are only benchmarks, but they are important to us. + +## Routers + +We measured the speeds of a bunch of JavaScript routers. +For example, `find-my-way` is a very fast router used inside Fastify. + +- @medley/router +- find-my-way +- koa-tree-router +- trek-router +- express (includes handling) +- koa-router + +First, we registered the following routing to each of our routers. +These are similar to those used in the real world. + +```ts twoslash +type Route = { + method: string; + path: string; +}; +// ---cut--- +export const routes: Route[] = [ + { method: "GET", path: "/user" }, + { method: "GET", path: "/user/comments" }, + { method: "GET", path: "/user/avatar" }, + { method: "GET", path: "/user/lookup/username/:username" }, + { method: "GET", path: "/user/lookup/email/:address" }, + { method: "GET", path: "/event/:id" }, + { method: "GET", path: "/event/:id/comments" }, + { method: "POST", path: "/event/:id/comment" }, + { method: "GET", path: "/map/:location/events" }, + { method: "GET", path: "/status" }, + { method: "GET", path: "/very/deeply/nested/route/hello/there" }, + { method: "GET", path: "/static/*" }, +]; +``` + +Then we sent the Request to the endpoints like below. + +```ts twoslash +type Route = { + method: string; + path: string; +}; +// ---cut--- +const routes: (Route & { name: string })[] = [ + { + name: "short static", + method: "GET", + path: "/user", + }, + { + name: "static with same radix", + method: "GET", + path: "/user/comments", + }, + { + name: "dynamic route", + method: "GET", + path: "/user/lookup/username/hey", + }, + { + name: "mixed static dynamic", + method: "GET", + path: "/event/abcd1234/comments", + }, + { + name: "post", + method: "POST", + path: "/event/abcd1234/comment", + }, + { + name: "long static", + method: "GET", + path: "/very/deeply/nested/route/hello/there", + }, + { + name: "wildcard", + method: "GET", + path: "/static/index.html", + }, +]; +``` + +Let's see the results. + +### On Node.js + +The following screenshots show the results on Node.js. + + + + + + + + + + + + + + + + + +### On Bun + +The following screenshots show the results on Bun. + + + + + + + + + + + + + + + + + +## Cloudflare Workers + +**Hono is the fastest**, compared to other routers for Cloudflare Workers. + +- Machine: Apple MacBook Pro, 32 GiB, M1 Pro +- Scripts: [benchmarks/handle-event](https://github.com/honojs/hono/tree/main/benchmarks/handle-event) + +``` +Hono x 402,820 ops/sec ±4.78% (80 runs sampled) +itty-router x 212,598 ops/sec ±3.11% (87 runs sampled) +sunder x 297,036 ops/sec ±4.76% (77 runs sampled) +worktop x 197,345 ops/sec ±2.40% (88 runs sampled) +Fastest is Hono +✨ Done in 28.06s. +``` + +## Deno + +**Hono is the fastest**, compared to other frameworks for Deno. + +- Machine: Apple MacBook Pro, 32 GiB, M1 Pro, Deno v1.22.0 +- Scripts: [benchmarks/deno](https://github.com/honojs/hono/tree/main/benchmarks/deno) +- Method: `bombardier --fasthttp -d 10s -c 100 'http://localhost:8000/user/lookup/username/foo'` + +| Framework | Version | Results | +| --------- | :----------: | -----------------------: | +| **Hono** | 3.0.0 | **Requests/sec: 136112** | +| Fast | 4.0.0-beta.1 | Requests/sec: 103214 | +| Megalo | 0.3.0 | Requests/sec: 64597 | +| Faster | 5.7 | Requests/sec: 54801 | +| oak | 10.5.1 | Requests/sec: 43326 | +| opine | 2.2.0 | Requests/sec: 30700 | + +Another benchmark result: [denosaurs/bench](https://github.com/denosaurs/bench) + +## Bun + +Hono is one of the fastest frameworks for Bun. +You can see it below. + +- [SaltyAom/bun-http-framework-benchmark](https://github.com/SaltyAom/bun-http-framework-benchmark) diff --git a/.cursor/rules/hono/concepts/developer-experience.mdc b/.cursor/rules/hono/concepts/developer-experience.mdc new file mode 100644 index 0000000..b19b68e --- /dev/null +++ b/.cursor/rules/hono/concepts/developer-experience.mdc @@ -0,0 +1,11 @@ +--- +description: Hono developer experience overview highlighting TypeScript support, intuitive APIs, and productivity features for modern web development +globs: +alwaysApply: false +--- + +# Developer Experience + +To create a great application, we need great development experience. +Fortunately, we can write applications for Cloudflare Workers, Deno, and Bun in TypeScript without having the need to transpile it to JavaScript. +Hono is written in TypeScript and can make applications type-safe. diff --git a/.cursor/rules/hono/concepts/middleware.mdc b/.cursor/rules/hono/concepts/middleware.mdc new file mode 100644 index 0000000..f83e1c5 --- /dev/null +++ b/.cursor/rules/hono/concepts/middleware.mdc @@ -0,0 +1,29 @@ +--- +description: Hono middleware concepts explaining the middleware architecture, execution flow, and how to create custom middleware for web applications +globs: +alwaysApply: false +--- + +# Middleware + +We call the primitive that returns `Response` as "Handler". +"Middleware" is executed before and after the Handler and handles the `Request` and `Response`. +It's like an onion structure. + + + +For example, we can write the middleware to add the "X-Response-Time" header as follows. + +```ts twoslash +import { Hono } from "hono"; +const app = new Hono(); +// ---cut--- +app.use(async (c, next) => { + const start = Date.now(); + await next(); + const end = Date.now(); + c.res.headers.set("X-Response-Time", `${end - start}`); +}); +``` + +With this simple method, we can write our own custom middleware and we can use the built-in or third party middleware. diff --git a/.cursor/rules/hono/concepts/motivation.mdc b/.cursor/rules/hono/concepts/motivation.mdc new file mode 100644 index 0000000..0a3d550 --- /dev/null +++ b/.cursor/rules/hono/concepts/motivation.mdc @@ -0,0 +1,29 @@ +--- +description: Hono motivation and philosophy explaining the framework's design principles, goals, and vision for modern web development +globs: +alwaysApply: false +--- + +# Philosophy + +In this section, we talk about the concept, or philosophy, of Hono. + +## Motivation + +At first, I just wanted to create a web application on Cloudflare Workers. +But, there was no good framework that works on Cloudflare Workers. +So, I started building Hono. + +I thought it would be a good opportunity to learn how to build a router using Trie trees. +Then a friend showed up with ultra crazy fast router called "RegExpRouter". +And I also have a friend who created the Basic authentication middleware. + +Using only Web Standard APIs, we could make it work on Deno and Bun. When people asked "is there Express for Bun?", we could answer, "no, but there is Hono". +(Although Express works on Bun now.) + +We also have friends who make GraphQL servers, Firebase authentication, and Sentry middleware. +And, we also have a Node.js adapter. +An ecosystem has sprung up. + +In other words, Hono is damn fast, makes a lot of things possible, and works anywhere. +We might imagine that Hono could become the **Standard for Web Standards**. diff --git a/.cursor/rules/hono/concepts/routers.mdc b/.cursor/rules/hono/concepts/routers.mdc new file mode 100644 index 0000000..b9c16da --- /dev/null +++ b/.cursor/rules/hono/concepts/routers.mdc @@ -0,0 +1,99 @@ +--- +description: Hono routing concepts explaining different router implementations, performance characteristics, and routing patterns for web applications +globs: +alwaysApply: false +--- + +# Routers + +The routers are the most important features for Hono. + +Hono has five routers. + +## RegExpRouter + +**RegExpRouter** is the fastest router in the JavaScript world. + +Although this is called "RegExp" it is not an Express-like implementation using [path-to-regexp](https://github.com/pillarjs/path-to-regexp). +They are using linear loops. +Therefore, regular expression matching will be performed for all routes and the performance will be degraded as you have more routes. + + + +Hono's RegExpRouter turns the route pattern into "one large regular expression". +Then it can get the result with one-time matching. + + + +This works faster than methods that use tree-based algorithms such as radix-tree in most cases. + +## TrieRouter + +**TrieRouter** is the router using the Trie-tree algorithm. +It does not use linear loops as same as RegExpRouter. + + + +This router is not as fast as the RegExpRouter, but it is much faster than the Express router. +TrieRouter supports all patterns though RegExpRouter does not. + +## SmartRouter + +RegExpRouter doesn't support all routing patterns. +Therefore, it's usually used in combination with another router that does support all patterns. + +**SmartRouter** will select the best router by inferring from the registered routers. +Hono uses SmartRouter and the two routers by default: + +```ts +// Inside the core of Hono. +readonly defaultRouter: Router = new SmartRouter({ + routers: [new RegExpRouter(), new TrieRouter()], +}) +``` + +When the application starts, SmartRouter detects the fastest router based on routing and continues to use it. + +## LinearRouter + +RegExpRouter is fast, but the route registration phase can be slightly slow. +So, it's not suitable for an environment that initializes with every request. + +**LinearRouter** is optimized for "one shot" situations. +Route registration is significantly faster than with RegExpRouter because it adds the route without compiling strings, using a linear approach. + +The following is one of the benchmark results, which includes the route registration phase. + +```console +• GET /user/lookup/username/hey +----------------------------------------------------- ----------------------------- +LinearRouter 1.82 µs/iter (1.7 µs … 2.04 µs) 1.84 µs 2.04 µs 2.04 µs +MedleyRouter 4.44 µs/iter (4.34 µs … 4.54 µs) 4.48 µs 4.54 µs 4.54 µs +FindMyWay 60.36 µs/iter (45.5 µs … 1.9 ms) 59.88 µs 78.13 µs 82.92 µs +KoaTreeRouter 3.81 µs/iter (3.73 µs … 3.87 µs) 3.84 µs 3.87 µs 3.87 µs +TrekRouter 5.84 µs/iter (5.75 µs … 6.04 µs) 5.86 µs 6.04 µs 6.04 µs + +summary for GET /user/lookup/username/hey + LinearRouter + 2.1x faster than KoaTreeRouter + 2.45x faster than MedleyRouter + 3.21x faster than TrekRouter + 33.24x faster than FindMyWay +``` + +For situations like Fastly Compute, it's better to use LinearRouter with the `hono/quick` preset. + +## PatternRouter + +**PatternRouter** is the smallest router among Hono's routers. + +While Hono is already compact, if you need to make it even smaller for an environment with limited resources, you can use PatternRouter. + +An application using only PatternRouter is under 15KB in size. + +```console +$ npx wrangler deploy --minify ./src/index.ts + ⛅️ wrangler 3.20.0 +------------------- +Total Upload: 14.68 KiB / gzip: 5.38 KiB +``` diff --git a/.cursor/rules/hono/concepts/stacks.mdc b/.cursor/rules/hono/concepts/stacks.mdc new file mode 100644 index 0000000..cdca6c6 --- /dev/null +++ b/.cursor/rules/hono/concepts/stacks.mdc @@ -0,0 +1,254 @@ +--- +description: Hono technology stacks and ecosystem overview covering integrations, tools, and recommended patterns for building full-stack applications +globs: +alwaysApply: false +--- + +# Hono Stacks + +Hono makes easy things easy and hard things easy. +It is suitable for not just only returning JSON. +But it's also great for building the full-stack application including REST API servers and the client. + +## RPC + +Hono's RPC feature allows you to share API specs with little change to your code. +The client generated by `hc` will read the spec and access the endpoint type-safety. + +The following libraries make it possible. + +- Hono - API Server +- [Zod](https://zod.dev) - Validator +- [Zod Validator Middleware](https://github.com/honojs/middleware/tree/main/packages/zod-validator) +- `hc` - HTTP Client + +We can call the set of these components the **Hono Stack**. +Now let's create an API server and a client with it. + +## Writing API + +First, write an endpoint that receives a GET request and returns JSON. + +```ts twoslash +import { Hono } from "hono"; + +const app = new Hono(); + +app.get("/hello", (c) => { + return c.json({ + message: `Hello!`, + }); +}); +``` + +## Validation with Zod + +Validate with Zod to receive the value of the query parameter. + + + +```ts +import { zValidator } from "@hono/zod-validator"; +import { z } from "zod"; + +app.get( + "/hello", + zValidator( + "query", + z.object({ + name: z.string(), + }) + ), + (c) => { + const { name } = c.req.valid("query"); + return c.json({ + message: `Hello! ${name}`, + }); + } +); +``` + +## Sharing the Types + +To emit an endpoint specification, export its type. + +::: warning + +For the RPC to infer routes correctly, all included methods must be chained, and the endpoint or app type must be inferred from a declared variable. For more, see [Best Practices for RPC](https://hono.dev/docs/guides/best-practices#if-you-want-to-use-rpc-features). + +::: + +```ts{1,17} +const route = app.get( + '/hello', + zValidator( + 'query', + z.object({ + name: z.string(), + }) + ), + (c) => { + const { name } = c.req.valid('query') + return c.json({ + message: `Hello! ${name}`, + }) + } +) + +export type AppType = typeof route +``` + +## Client + +Next. The client-side implementation. +Create a client object by passing the `AppType` type to `hc` as generics. +Then, magically, completion works and the endpoint path and request type are suggested. + + + +```ts +import { hc } from "hono/client"; + +import { AppType } from "./server"; + +const client = hc
+
+
+
+ );
+}
+```
diff --git a/.cursor/rules/hono/concepts/web-standard.mdc b/.cursor/rules/hono/concepts/web-standard.mdc
new file mode 100644
index 0000000..8c0a681
--- /dev/null
+++ b/.cursor/rules/hono/concepts/web-standard.mdc
@@ -0,0 +1,39 @@
+---
+description: Hono Web Standards compliance explaining how the framework leverages standard web APIs for cross-platform compatibility
+globs:
+alwaysApply: false
+---
+
+# Web Standards
+
+Hono uses only **Web Standards** like Fetch.
+They were originally used in the `fetch` function and consist of basic objects that handle HTTP requests and responses.
+In addition to `Requests` and `Responses`, there are `URL`, `URLSearchParam`, `Headers` and others.
+
+Cloudflare Workers, Deno, and Bun also build upon Web Standards.
+For example, a server that returns "Hello World" could be written as below. This could run on Cloudflare Workers and Bun.
+
+```ts twoslash
+export default {
+ async fetch() {
+ return new Response("Hello World");
+ },
+};
+```
+
+Hono uses only Web Standards, which means that Hono can run on any runtime that supports them.
+In addition, we have a Node.js adapter. Hono runs on these runtimes:
+
+- Cloudflare Workers (`workerd`)
+- Deno
+- Bun
+- Fastly Compute
+- AWS Lambda
+- Node.js
+- Vercel (edge-light)
+
+It also works on Netlify and other platforms.
+The same code runs on all platforms.
+
+Cloudflare Workers, Deno, Shopify, and others launched [WinterCG](https://wintercg.org) to discuss the possibility of using the Web Standards to enable "web-interoperability".
+Hono will follow their steps and go for **the Standard of the Web Standards**.
diff --git a/.cursor/rules/hono/getting-started/ali-function-compute.mdc b/.cursor/rules/hono/getting-started/ali-function-compute.mdc
new file mode 100644
index 0000000..42c83f8
--- /dev/null
+++ b/.cursor/rules/hono/getting-started/ali-function-compute.mdc
@@ -0,0 +1,124 @@
+---
+description: Hono getting started guide for Alibaba Cloud Function Compute deployment with serverless functions and cloud integration
+globs:
+alwaysApply: false
+---
+
+# Alibaba Cloud Function Compute
+
+[Alibaba Cloud Function Compute](https://www.alibabacloud.com/en/product/function-compute) is a fully managed, event-driven compute service. Function Compute allows you to focus on writing and uploading code without having to manage infrastructure such as servers.
+
+This guide uses a third-party adapter [rwv/hono-alibaba-cloud-fc3-adapter](https://github.com/rwv/hono-alibaba-cloud-fc3-adapter) to run Hono on Alibaba Cloud Function Compute.
+
+## 1. Setup
+
+::: code-group
+
+```sh [npm]
+mkdir my-app
+cd my-app
+npm i hono hono-alibaba-cloud-fc3-adapter
+npm i -D @serverless-devs/s esbuild
+mkdir src
+touch src/index.ts
+```
+
+```sh [yarn]
+mkdir my-app
+cd my-app
+yarn add hono hono-alibaba-cloud-fc3-adapter
+yarn add -D @serverless-devs/s esbuild
+mkdir src
+touch src/index.ts
+```
+
+```sh [pnpm]
+mkdir my-app
+cd my-app
+pnpm add hono hono-alibaba-cloud-fc3-adapter
+pnpm add -D @serverless-devs/s esbuild
+mkdir src
+touch src/index.ts
+```
+
+```sh [bun]
+mkdir my-app
+cd my-app
+bun add hono hono-alibaba-cloud-fc3-adapter
+bun add -D esbuild @serverless-devs/s
+mkdir src
+touch src/index.ts
+```
+
+:::
+
+## 2. Hello World
+
+Edit `src/index.ts`.
+
+```ts
+import { Hono } from "hono";
+import { handle } from "hono-alibaba-cloud-fc3-adapter";
+
+const app = new Hono();
+
+app.get("/", c => c.text("Hello Hono!"));
+
+export const handler = handle(app);
+```
+
+## 3. Setup serverless-devs
+
+> [serverless-devs](https://github.com/Serverless-Devs/Serverless-Devs) is an open source and open serverless developer platform dedicated to providing developers with a powerful tool chain system. Through this platform, developers can not only experience multi cloud serverless products with one click and rapidly deploy serverless projects, but also manage projects in the whole life cycle of serverless applications, and combine serverless devs with other tools / platforms very simply and quickly to further improve the efficiency of R & D, operation and maintenance.
+
+Add the Alibaba Cloud AccessKeyID & AccessKeySecret
+
+```sh
+npx s config add
+# Please select a provider: Alibaba Cloud (alibaba)
+# Input your AccessKeyID & AccessKeySecret
+```
+
+Edit `s.yaml`
+
+```yaml
+edition: 3.0.0
+name: my-app
+access: default
+
+vars:
+ region: us-west-1
+
+resources:
+ my-app:
+ component: fc3
+ props:
+ region: ${vars.region}
+ functionName: my-app
+ description: Hello World by Hono
+ runtime: nodejs20
+ code: ./dist
+ handler: index.handler
+ memorySize: 1024
+ timeout: 300
+```
+
+Edit `scripts` section in `package.json`:
+
+```json
+{
+ "scripts": {
+ "build": "esbuild --bundle --outfile=./dist/index.js --platform=node --target=node20 ./src/index.ts",
+ "deploy": "s deploy -y"
+ }
+}
+```
+
+## 4. Deploy
+
+Finally, run the command to deploy:
+
+```sh
+npm run build # Compile the TypeScript code to JavaScript
+npm run deploy # Deploy the function to Alibaba Cloud Function Compute
+```
diff --git a/.cursor/rules/hono/getting-started/aws-lambda.mdc b/.cursor/rules/hono/getting-started/aws-lambda.mdc
new file mode 100644
index 0000000..694c552
--- /dev/null
+++ b/.cursor/rules/hono/getting-started/aws-lambda.mdc
@@ -0,0 +1,235 @@
+---
+description: Hono getting started guide for AWS Lambda deployment with serverless functions, API Gateway integration, and cloud deployment
+globs:
+alwaysApply: false
+---
+
+# AWS Lambda
+
+AWS Lambda is a serverless platform by Amazon Web Services.
+You can run your code in response to events and automatically manages the underlying compute resources for you.
+
+Hono works on AWS Lambda with the Node.js 18+ environment.
+
+## 1. Setup
+
+When creating the application on AWS Lambda,
+[CDK](https://docs.aws.amazon.com/cdk/v2/guide/home.html)
+is useful to setup the functions such as IAM Role, API Gateway, and others.
+
+Initialize your project with the `cdk` CLI.
+
+::: code-group
+
+```sh [npm]
+mkdir my-app
+cd my-app
+cdk init app -l typescript
+npm i hono
+npm i -D esbuild
+mkdir lambda
+touch lambda/index.ts
+```
+
+```sh [yarn]
+mkdir my-app
+cd my-app
+cdk init app -l typescript
+yarn add hono
+yarn add -D esbuild
+mkdir lambda
+touch lambda/index.ts
+```
+
+```sh [pnpm]
+mkdir my-app
+cd my-app
+cdk init app -l typescript
+pnpm add hono
+pnpm add -D esbuild
+mkdir lambda
+touch lambda/index.ts
+```
+
+```sh [bun]
+mkdir my-app
+cd my-app
+cdk init app -l typescript
+bun add hono
+bun add -D esbuild
+mkdir lambda
+touch lambda/index.ts
+```
+
+:::
+
+## 2. Hello World
+
+Edit `lambda/index.ts`.
+
+```ts
+import { Hono } from "hono";
+import { handle } from "hono/aws-lambda";
+
+const app = new Hono();
+
+app.get("/", c => c.text("Hello Hono!"));
+
+export const handler = handle(app);
+```
+
+## 3. Deploy
+
+Edit `lib/my-app-stack.ts`.
+
+```ts
+import * as cdk from "aws-cdk-lib";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
+import { Construct } from "constructs";
+
+export class MyAppStack extends cdk.Stack {
+ constructor(scope: Construct, id: string, props?: cdk.StackProps) {
+ super(scope, id, props);
+
+ const fn = new NodejsFunction(this, "lambda", {
+ entry: "lambda/index.ts",
+ handler: "handler",
+ runtime: lambda.Runtime.NODEJS_22_X,
+ });
+ const fnUrl = fn.addFunctionUrl({
+ authType: lambda.FunctionUrlAuthType.NONE,
+ });
+ new cdk.CfnOutput(this, "lambdaUrl", {
+ value: fnUrl.url!
+ });
+ }
+}
+```
+
+Finally, run the command to deploy:
+
+```sh
+cdk deploy
+```
+
+## Serve Binary data
+
+Hono supports binary data as a response.
+In Lambda, base64 encoding is required to return binary data.
+Once binary type is set to `Content-Type` header, Hono automatically encodes data to base64.
+
+```ts
+app.get("/binary", async (c) => {
+ // ...
+ c.status(200);
+ c.header("Content-Type", "image/png"); // means binary data
+ return c.body(buffer); // supports `ArrayBufferLike` type, encoded to base64.
+});
+```
+
+## Access AWS Lambda Object
+
+In Hono, you can access the AWS Lambda Events and Context by binding the `LambdaEvent`, `LambdaContext` type and using `c.env`
+
+```ts
+import type { LambdaContext, LambdaEvent } from "hono/aws-lambda";
+
+import { Hono } from "hono";
+import { handle } from "hono/aws-lambda";
+
+type Bindings = {
+ event: LambdaEvent;
+ lambdaContext: LambdaContext;
+};
+
+const app = new Hono<{ Bindings: Bindings }>();
+
+app.get("/aws-lambda-info/", (c) => {
+ return c.json({
+ isBase64Encoded: c.env.event.isBase64Encoded,
+ awsRequestId: c.env.lambdaContext.awsRequestId,
+ });
+});
+
+export const handler = handle(app);
+```
+
+## Access RequestContext
+
+In Hono, you can access the AWS Lambda request context by binding the `LambdaEvent` type and using `c.env.event.requestContext`.
+
+```ts
+import type { LambdaEvent } from "hono/aws-lambda";
+
+import { Hono } from "hono";
+import { handle } from "hono/aws-lambda";
+
+type Bindings = {
+ event: LambdaEvent;
+};
+
+const app = new Hono<{ Bindings: Bindings }>();
+
+app.get("/custom-context/", (c) => {
+ const lambdaContext = c.env.event.requestContext;
+ return c.json(lambdaContext);
+});
+
+export const handler = handle(app);
+```
+
+### Before v3.10.0 (deprecated)
+
+you can access the AWS Lambda request context by binding the `ApiGatewayRequestContext` type and using `c.env.`
+
+```ts
+import type { ApiGatewayRequestContext } from "hono/aws-lambda";
+
+import { Hono } from "hono";
+import { handle } from "hono/aws-lambda";
+
+type Bindings = {
+ requestContext: ApiGatewayRequestContext;
+};
+
+const app = new Hono<{ Bindings: Bindings }>();
+
+app.get("/custom-context/", (c) => {
+ const lambdaContext = c.env.requestContext;
+ return c.json(lambdaContext);
+});
+
+export const handler = handle(app);
+```
+
+## Lambda response streaming
+
+By changing the invocation mode of AWS Lambda, you can achieve [Streaming Response](https://aws.amazon.com/blogs/compute/introducing-aws-lambda-response-streaming/).
+
+```diff
+fn.addFunctionUrl({
+ authType: lambda.FunctionUrlAuthType.NONE,
++ invokeMode: lambda.InvokeMode.RESPONSE_STREAM,
+})
+```
+
+Typically, the implementation requires writing chunks to NodeJS.WritableStream using awslambda.streamifyResponse, but with the AWS Lambda Adaptor, you can achieve the traditional streaming response of Hono by using streamHandle instead of handle.
+
+```ts
+import { Hono } from "hono";
+import { streamHandle } from "hono/aws-lambda";
+
+const app = new Hono();
+
+app.get("/stream", async (c) => {
+ return streamText(c, async (stream) => {
+ for (let i = 0; i < 3; i++) {
+ await stream.writeln(`${i}`);
+ await stream.sleep(1);
+ }
+ });
+});
+
+export const handler = streamHandle(app);
+```
diff --git a/.cursor/rules/hono/getting-started/azure-functions.mdc b/.cursor/rules/hono/getting-started/azure-functions.mdc
new file mode 100644
index 0000000..f0d6a9f
--- /dev/null
+++ b/.cursor/rules/hono/getting-started/azure-functions.mdc
@@ -0,0 +1,167 @@
+---
+description: Hono getting started guide for Azure Functions deployment with serverless computing, HTTP triggers, and cloud integration
+globs:
+alwaysApply: false
+---
+
+# Azure Functions
+
+[Azure Functions](https://azure.microsoft.com/en-us/products/functions) is a serverless platform from Microsoft Azure. You can run your code in response to events, and it automatically manages the underlying compute resources for you.
+
+Hono was not designed for Azure Functions at first. But with [Azure Functions Adapter](https://github.com/Marplex/hono-azurefunc-adapter) it can run on it as well.
+
+It works with Azure Functions **V4** running on Node.js 18 or above.
+
+## 1. Install CLI
+
+To create an Azure Function, you must first install [Azure Functions Core Tools](https://learn.microsoft.com/en-us/azure/azure-functions/create-first-function-cli-typescript?pivots=nodejs-model-v4#install-the-azure-functions-core-tools).
+
+On macOS
+
+```sh
+brew tap azure/functions
+brew install azure-functions-core-tools@4
+```
+
+Follow this link for other OS:
+
+- [Install the Azure Functions Core Tools | Microsoft Learn](https://learn.microsoft.com/en-us/azure/azure-functions/create-first-function-cli-typescript?pivots=nodejs-model-v4#install-the-azure-functions-core-tools)
+
+## 2. Setup
+
+Create a TypeScript Node.js V4 project in the current folder.
+
+```sh
+func init --typescript
+```
+
+Change the default route prefix of the host. Add this property to the root json object of `host.json`:
+
+```json
+"extensions": {
+ "http": {
+ "routePrefix": ""
+ }
+}
+```
+
+::: info
+The default Azure Functions route prefix is `/api`. If you don't change it as shown above, be sure to start all your Hono routes with `/api`
+:::
+
+Now you are ready to install Hono and the Azure Functions Adapter with:
+
+::: code-group
+
+```sh [npm]
+npm i @marplex/hono-azurefunc-adapter hono
+```
+
+```sh [yarn]
+yarn add @marplex/hono-azurefunc-adapter hono
+```
+
+```sh [pnpm]
+pnpm add @marplex/hono-azurefunc-adapter hono
+```
+
+```sh [bun]
+bun add @marplex/hono-azurefunc-adapter hono
+```
+
+:::
+
+## 3. Hello World
+
+Create `src/app.ts`:
+
+```ts
+// src/app.ts
+import { Hono } from "hono";
+const app = new Hono();
+
+app.get("/", c => c.text("Hello Azure Functions!"));
+
+export default app;
+```
+
+Create `src/functions/httpTrigger.ts`:
+
+```ts
+// src/functions/httpTrigger.ts
+import { app } from "@azure/functions";
+import { azureHonoHandler } from "@marplex/hono-azurefunc-adapter";
+
+import honoApp from "../app";
+
+app.http("httpTrigger", {
+ methods: [
+ // Add all your supported HTTP methods here
+ "GET",
+ "POST",
+ "DELETE",
+ "PUT",
+ ],
+ authLevel: "anonymous",
+ route: "{*proxy}",
+ handler: azureHonoHandler(honoApp.fetch),
+});
+```
+
+## 4. Run
+
+Run the development server locally. Then, access `http://localhost:7071` in your Web browser.
+
+::: code-group
+
+```sh [npm]
+npm run start
+```
+
+```sh [yarn]
+yarn start
+```
+
+```sh [pnpm]
+pnpm start
+```
+
+```sh [bun]
+bun run start
+```
+
+:::
+
+## 5. Deploy
+
+::: info
+Before you can deploy to Azure, you need to create some resources in your cloud infrastructure. Please visit the Microsoft documentation on [Create supporting Azure resources for your function](https://learn.microsoft.com/en-us/azure/azure-functions/create-first-function-cli-typescript?pivots=nodejs-model-v4&tabs=windows%2Cazure-cli%2Cbrowser#create-supporting-azure-resources-for-your-function)
+:::
+
+Build the project for deployment:
+
+::: code-group
+
+```sh [npm]
+npm run build
+```
+
+```sh [yarn]
+yarn build
+```
+
+```sh [pnpm]
+pnpm build
+```
+
+```sh [bun]
+bun run build
+```
+
+:::
+
+Deploy your project to the function app in Azure Cloud. Replace `-
+ {query.data?.todos.map(todo => (
+
- {todo.title} + ))} +
Hello Hono!
+ + + ); +} + +app.get("/page", (c) => { + return c.html(Hello, Cloudflare Pages!
); +}); + +export default app; +``` + +## 3. Run + +Run the development server locally. Then, access `http://localhost:5173` in your Web browser. + +::: code-group + +```sh [npm] +npm run dev +``` + +```sh [yarn] +yarn dev +``` + +```sh [pnpm] +pnpm dev +``` + +```sh [bun] +bun run dev +``` + +::: + +## 4. Deploy + +If you have a Cloudflare account, you can deploy to Cloudflare. In `package.json`, `$npm_execpath` needs to be changed to your package manager of choice. + +::: code-group + +```sh [npm] +npm run deploy +``` + +```sh [yarn] +yarn deploy +``` + +```sh [pnpm] +pnpm run deploy +``` + +```sh [bun] +bun run deploy +``` + +::: + +### Deploy via the Cloudflare dashboard with GitHub + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account. +2. In Account Home, select Workers & Pages > Create application > Pages > Connect to Git. +3. Authorize your GitHub account, and select the repository. In Set up builds and deployments, provide the following information: + +| Configuration option | Value | +| -------------------- | --------------- | +| Production branch | `main` | +| Build command | `npm run build` | +| Build directory | `dist` | + +## Bindings + +You can use Cloudflare Bindings like Variables, KV, D1, and others. +In this section, let's use Variables and KV. + +### Create `wrangler.toml` + +First, create `wrangler.toml` for local Bindings: + +```sh +touch wrangler.toml +``` + +Edit `wrangler.toml`. Specify Variable with the name `MY_NAME`. + +```toml +[vars] +MY_NAME = "Hono" +``` + +### Create KV + +Next, make the KV. Run the following `wrangler` command: + +```sh +wrangler kv namespace create MY_KV --preview +``` + +Note down the `preview_id` as the following output: + +``` +{ binding = "MY_KV", preview_id = "abcdef" } +``` + +Specify `preview_id` with the name of Bindings, `MY_KV`: + +```toml +[[kv_namespaces]] +binding = "MY_KV" +id = "abcdef" +``` + +### Edit `vite.config.ts` + +Edit the `vite.config.ts`: + +```ts +import build from "@hono/vite-cloudflare-pages"; +import devServer from "@hono/vite-dev-server"; +import adapter from "@hono/vite-dev-server/cloudflare"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + devServer({ + entry: "src/index.tsx", + adapter, // Cloudflare Adapter + }), + build(), + ], +}); +``` + +### Use Bindings in your application + +Use Variable and KV in your application. Set the types. + +```ts +type Bindings = { + MY_NAME: string; + MY_KV: KVNamespace; +}; + +const app = new Hono<{ Bindings: Bindings }>(); +``` + +Use them: + +```tsx +app.get("/", async (c) => { + await c.env.MY_KV.put("name", c.env.MY_NAME); + const name = await c.env.MY_KV.get("name"); + return c.render( ++ Hello! + {name} +
+ ); +}); +``` + +### In production + +For Cloudflare Pages, you will use `wrangler.toml` for local development, but for production, you will set up Bindings in the dashboard. + +## Client-side + +You can write client-side scripts and import them into your application using Vite's features. +If `/src/client.ts` is the entry point for the client, simply write it in the script tag. +Additionally, `import.meta.env.PROD` is useful for detecting whether it's running on a dev server or in the build phase. + +```tsx +app.get("/", (c) => { + return c.html( + + + {import.meta.env.PROD + ? ( + + ) + : ( + + )} + + +Hello
+ + + ); +}); +``` + +In order to build the script properly, you can use the example config file `vite.config.ts` as shown below. + +```ts +import pages from "@hono/vite-cloudflare-pages"; +import devServer from "@hono/vite-dev-server"; +import { defineConfig } from "vite"; + +export default defineConfig(({ mode }) => { + if (mode === "client") { + return { + build: { + rollupOptions: { + input: "./src/client.ts", + output: { + entryFileNames: "static/client.js", + }, + }, + }, + }; + } + else { + return { + plugins: [ + pages(), + devServer({ + entry: "src/index.tsx", + }), + ], + }; + } +}); +``` + +You can run the following command to build the server and client script. + +```sh +vite build --mode client && vite build +``` + +## Cloudflare Pages Middleware + +Cloudflare Pages uses its own [middleware](https://developers.cloudflare.com/pages/functions/middleware/) system that is different from Hono's middleware. You can enable it by exporting `onRequest` in a file named `_middleware.ts` like this: + +```ts +// functions/_middleware.ts +export async function onRequest(pagesContext) { + console.log(`You are accessing ${pagesContext.request.url}`); + return await pagesContext.next(); +} +``` + +Using `handleMiddleware`, you can use Hono's middleware as Cloudflare Pages middleware. + +```ts +// functions/_middleware.ts +import { handleMiddleware } from "hono/cloudflare-pages"; + +export const onRequest = handleMiddleware(async (c, next) => { + console.log(`You are accessing ${c.req.url}`); + await next(); +}); +``` + +You can also use built-in and 3rd party middleware for Hono. For example, to add Basic Authentication, you can use [Hono's Basic Authentication Middleware](/docs/middleware/builtin/basic-auth). + +```ts +import { basicAuth } from "hono/basic-auth"; +// functions/_middleware.ts +import { handleMiddleware } from "hono/cloudflare-pages"; + +export const onRequest = handleMiddleware( + basicAuth({ + username: "hono", + password: "acoolproject", + }) +); +``` + +If you want to apply multiple middleware, you can write it like this: + +```ts +import { handleMiddleware } from "hono/cloudflare-pages"; + +// ... + +export const onRequest = [ + handleMiddleware(middleware1), + handleMiddleware(middleware2), + handleMiddleware(middleware3), +]; +``` + +### Accessing `EventContext` + +You can access [`EventContext`](https://developers.cloudflare.com/pages/functions/api-reference/#eventcontext) object via `c.env` in `handleMiddleware`. + +```ts +// functions/_middleware.ts +import { handleMiddleware } from "hono/cloudflare-pages"; + +export const onRequest = [ + handleMiddleware(async (c, next) => { + c.env.eventContext.data.user = "Joe"; + await next(); + }), +]; +``` + +Then, you can access the data value in via `c.env.eventContext` in the handler: + +```ts +// functions/api/[[route]].ts +import type { EventContext } from "hono/cloudflare-pages"; + +import { handle } from "hono/cloudflare-pages"; + +// ... + +type Env = { + Bindings: { + eventContext: EventContext; + }; +}; + +const app = new Hono
+
+ );
+}
+
+function App() {
+ return (
+
+
+ + Count: + {count} +
+ +
+ {!showLargeImage
+ ? (
+ 
+ )
+ : (
+
+
+ );
+}
+```
+
+### 2. Using `viewTransition()` with `keyframes()`
+
+The `viewTransition()` function allows you to get the unique `view-transition-name`.
+
+You can use it with the `keyframes()`, The `::view-transition-old()` is converted to `::view-transition-old(${uniqueName))`.
+
+```tsx
+import { css, keyframes, Style } from "hono/css";
+import { startViewTransition, useState } from "hono/jsx";
+import { viewTransition } from "hono/jsx/dom/css";
+
+const rotate = keyframes`
+ from {
+ rotate: 0deg;
+ }
+ to {
+ rotate: 360deg;
+ }
+`;
+
+export default function App() {
+ const [showLargeImage, setShowLargeImage] = useState(false);
+ const [transitionNameClass] = useState(() =>
+ viewTransition(css`
+ ::view-transition-old() {
+ animation-name: ${rotate};
+ }
+ ::view-transition-new() {
+ animation-name: ${rotate};
+ }
+ `)
+ );
+ return (
+ <>
+
+
+
+ )
+ : (
+
+
+ )}
+
+ {!showLargeImage
+ ? (
+
+ )
+ : (
+
+
+ );
+}
+```
+
+### 3. Using `useViewTransition`
+
+If you want to change the style only during the animation. You can use `useViewTransition()`. This hook returns the `[boolean, (callback: () => void) => void]`, and they are the `isUpdating` flag and the `startViewTransition()` function.
+
+When this hook is used, the Component is evaluated at the following two times.
+
+- Inside the callback of a call to `startViewTransition()`.
+- When [the `finish` promise becomes fulfilled](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition/finished)
+
+```tsx
+import { css, keyframes, Style } from "hono/css";
+import { useState, useViewTransition } from "hono/jsx";
+import { viewTransition } from "hono/jsx/dom/css";
+
+const rotate = keyframes`
+ from {
+ rotate: 0deg;
+ }
+ to {
+ rotate: 360deg;
+ }
+`;
+
+export default function App() {
+ const [isUpdating, startViewTransition] = useViewTransition();
+ const [showLargeImage, setShowLargeImage] = useState(false);
+ const [transitionNameClass] = useState(() =>
+ viewTransition(css`
+ ::view-transition-old() {
+ animation-name: ${rotate};
+ }
+ ::view-transition-new() {
+ animation-name: ${rotate};
+ }
+ `)
+ );
+ return (
+ <>
+
+
+
+ )
+ : (
+
+
+ )}
+
+ {!showLargeImage
+ ? (
+
+ )
+ : (
+
+
+ );
+}
+```
+
+## The `hono/jsx/dom` runtime
+
+There is a small JSX Runtime for Client Components. Using this will result in smaller bundled results than using `hono/jsx`. Specify `hono/jsx/dom` in `tsconfig.json`. For Deno, modify the deno.json.
+
+```json
+{
+ "compilerOptions": {
+ "jsx": "react-jsx",
+ "jsxImportSource": "hono/jsx/dom"
+ }
+}
+```
+
+Alternatively, you can specify `hono/jsx/dom` in the esbuild transform options in `vite.config.ts`.
+
+```ts
+import { defineConfig } from "vite";
+
+export default defineConfig({
+ esbuild: {
+ jsxImportSource: "hono/jsx/dom",
+ },
+});
+```
diff --git a/.cursor/rules/hono/guides/jsx.mdc b/.cursor/rules/hono/guides/jsx.mdc
new file mode 100644
index 0000000..db142e4
--- /dev/null
+++ b/.cursor/rules/hono/guides/jsx.mdc
@@ -0,0 +1,400 @@
+---
+description: Hono JSX guide for server-side rendering with React-like syntax, component patterns, and templating in web applications
+globs:
+alwaysApply: false
+---
+
+# JSX
+
+You can write HTML with JSX syntax with `hono/jsx`.
+
+Although `hono/jsx` works on the client, you will probably use it most often when rendering content on the server side. Here are some things related to JSX that are common to both server and client.
+
+## Settings
+
+To use JSX, modify the `tsconfig.json`:
+
+`tsconfig.json`:
+
+```json
+{
+ "compilerOptions": {
+ "jsx": "react-jsx",
+ "jsxImportSource": "hono/jsx"
+ }
+}
+```
+
+Alternatively, use the pragma directives:
+
+```ts
+/** @jsx jsx */
+/** @jsxImportSource hono/jsx */
+```
+
+For Deno, you have to modify the `deno.json` instead of the `tsconfig.json`:
+
+```json
+{
+ "compilerOptions": {
+ "jsx": "precompile",
+ "jsxImportSource": "hono/jsx"
+ }
+}
+```
+
+## Usage
+
+:::info
+If you are comming straight from the [Quick Start](/docs/#quick-start), the main file has a `.ts` extension - you need to change it to `.tsx` - otherwise you will not be able to run the application at all. You should additionally modify the `package.json` (or `deno.json` if you are using Deno) to reflect that change (e.g. instead of having `bun run --hot src/index.ts` in dev script, you should have `bun run --hot src/index.tsx`).
+:::
+
+`index.tsx`:
+
+```tsx
+import type { FC } from "hono/jsx";
+
+import { Hono } from "hono";
+
+const app = new Hono();
+
+const Layout: FC = (props) => {
+ return (
+
+ {props.children}
+
+ );
+};
+
+const Top: FC<{ messages: string[] }> = (props: {
+ messages: string[];
+}) => {
+ return (
+
+ )
+ : (
+
+
+ )}
+ Hello Hono!
+-
+ {props.messages.map((message) => {
+ return (
+
- + {message} + !! + + ); + })} +
first child
+second child
+third child
+first child
+second child
+third child
+ + ); +} +``` + +## `PropsWithChildren` + +You can use `PropsWithChildren` to correctly infer a child element in a function component. + +```tsx +import { PropsWithChildren } from "hono/jsx"; + +type Post = { + id: number; + title: string; +}; + +function Component({ title, children }: PropsWithChildren
+
+ );
+}
+```
+
+## Inserting Raw HTML
+
+To directly insert HTML, use `dangerouslySetInnerHTML`:
+
+```tsx
+app.get("/foo", (c) => {
+ const inner = { __html: "JSX · SSR" };
+ const Div = ;
+});
+```
+
+## Memoization
+
+Optimize your components by memoizing computed strings using `memo`:
+
+```tsx
+import { memo } from "hono/jsx";
+
+const Header = memo(() => {title}
+ {children} +
+
+);
+```
+
+## Context
+
+By using `useContext`, you can share data globally across any level of the Component tree without passing values through props.
+
+```tsx
+import type { FC } from "hono/jsx";
+
+import { createContext, useContext } from "hono/jsx";
+
+const themes = {
+ light: {
+ color: "#000000",
+ background: "#eeeeee",
+ },
+ dark: {
+ color: "#ffffff",
+ background: "#222222",
+ },
+};
+
+const ThemeContext = createContext(themes.light);
+
+const Button: FC = () => {
+ const theme = useContext(ThemeContext);
+ return ;
+};
+
+const Toolbar: FC = () => {
+ return (
+ Hono is cool!
+ +
+
+
+ );
+};
+
+// ...
+
+app.get("/", (c) => {
+ return c.html(
+
+
+
+
+ );
+});
+```
+
+## Async Component
+
+`hono/jsx` supports an Async Component, so you can use `async`/`await` in your component.
+If you render it with `c.html()`, it will await automatically.
+
+```tsx
+async function AsyncComponent() {
+ await new Promise(r => setTimeout(r, 1000)); // sleep 1s
+ return Done!
;
+}
+
+app.get("/", (c) => {
+ return c.html(
+
+
+ Hello
;
+}
+
+app.get("/sync", async (c) => {
+ return c.html(
+
+
+ Hello
;
+}
+
+app.get("/with-suspense", async (c) => {
+ return c.html(
+
+
+ + Hello + {props.name} +
+failed to load
;
+ if (isLoading)
+ return loading...
;
+
+ return {data?.message}
; +} + +export default App; +``` + +## Using RPC with larger applications + +In the case of a larger application, such as the example mentioned in [Building a larger application](/docs/guides/best-practices#building-a-larger-application), you need to be careful about the type of inference. +A simple way to do this is to chain the handlers so that the types are always inferred. + +```ts +// authors.ts +import { Hono } from "hono"; + +const app = new Hono() + .get("/", c => c.json("list authors")) + .post("/", c => c.json("create an author", 201)) + .get("/:id", c => c.json(`get ${c.req.param("id")}`)); + +export default app; +``` + +```ts +// books.ts +import { Hono } from "hono"; + +const app = new Hono() + .get("/", c => c.json("list books")) + .post("/", c => c.json("create a book", 201)) + .get("/:id", c => c.json(`get ${c.req.param("id")}`)); + +export default app; +``` + +You can then import the sub-routers as you usually would, and make sure you chain their handlers as well, since this is the top level of the app in this case, this is the type we'll want to export. + +```ts +// index.ts +import { Hono } from "hono"; + +import authors from "./authors"; +import books from "./books"; + +const app = new Hono(); + +const routes = app.route("/authors", authors).route("/books", books); + +export default app; +export type AppType = typeof routes; +``` + +You can now create a new client using the registered AppType and use it as you would normally. + +## Known issues + +### IDE performance + +When using RPC, the more routes you have, the slower your IDE will become. One of the main reasons for this is that massive amounts of type instantiations are executed to infer the type of your app. + +For example, suppose your app has a route like this: + +```ts +// app.ts +export const app = new Hono().get("foo/:id", c => + c.json({ ok: true }, 200)); +``` + +Hono will infer the type as follows: + +```ts +export const app = HonoHello!
+ + + ) +}) +``` + +You can style pseudo-classes like `:hover` by using the [nesting selector](https://developer.mozilla.org/en-US/docs/Web/CSS/Nesting_selector), `&`: + +```ts +const buttonClass = css` + background-color: #fff; + &:hover { + background-color: red; + } +` +``` + +### Extending + +You can extend the CSS definition by embedding the class name. + +```tsx +const baseClass = css` + color: white; + background-color: blue; +` + +const header1Class = css` + ${baseClass} + font-size: 3rem; +` + +const header2Class = css` + ${baseClass} + font-size: 2rem; +` +``` + +In addition, the syntax of `${baseClass} {}` enables nesting classes. + +```tsx +const headerClass = css` + color: white; + background-color: blue; +` +const containerClass = css` + ${headerClass} { + h1 { + font-size: 3rem; + } + } +` +return c.render( +
+
+
+
+)
+```
+
+### Global styles
+
+A pseudo-selector called `:-hono-global` allows you to define global styles.
+
+```tsx
+const globalClass = css`
+ :-hono-global {
+ html {
+ font-family: Arial, Helvetica, sans-serif;
+ }
+ }
+`
+
+return c.render(
+ Hello!
+
+
+)
+```
+
+Or you can write CSS in the `` component with the `css` literal.
+
+```tsx
+export const renderer = jsxRenderer(({ children, title }) => {
+ return (
+
+
+
+ Hello!
+Today is a good day.
+{children}
+
+
+ )
+})
+```
+
+## `keyframes` Hello!
+ + + ) +}) +``` + +## Tips + +If you use VS Code, you can use [vscode-styled-components](https://marketplace.visualstudio.com/items?itemName=styled-components.vscode-styled-components) for Syntax highlighting and IntelliSense for css tagged literals. + + diff --git a/.cursor/rules/hono/helpers/dev.mdc b/.cursor/rules/hono/helpers/dev.mdc new file mode 100644 index 0000000..2cd0977 --- /dev/null +++ b/.cursor/rules/hono/helpers/dev.mdc @@ -0,0 +1,70 @@ +--- +description: Hono Dev helper for development utilities and debugging tools to enhance the development experience with Hono applications +globs: +alwaysApply: false +--- + +# Dev Helper + +Dev Helper provides useful methods you can use in development. + +```ts +import { Hono } from 'hono' +import { getRouterName, showRoutes } from 'hono/dev' +``` + +## `getRouterName()` + +You can get the name of the currently used router with `getRouterName()`. + +```ts +const app = new Hono() + +// ... + +console.log(getRouterName(app)) +``` + +## `showRoutes()` + +`showRoutes()` function displays the registered routes in your console. + +Consider an application like the following: + +```ts +const app = new Hono().basePath('/v1') + +app.get('/posts', (c) => { + // ... +}) + +app.get('/posts/:id', (c) => { + // ... +}) + +app.post('/posts', (c) => { + // ... +}) + +showRoutes(app, { + verbose: true, +}) +``` + +When this application starts running, the routes will be shown in your console as follows: + +```txt +GET /v1/posts +GET /v1/posts/:id +POST /v1/posts +``` + +## Options + +###Hello! ${username}!
` + ) +}) +``` + +### Insert snippets into JSX + +Insert the inline script into JSX: + +```tsx +app.get('/', (c) => { + return c.html( + + +Hello {props.name}
+I'm ${raw(name)}.
`) +}) +``` + +## Tips + +Thanks to these libraries, Visual Studio Code and vim also interprets template literals as HTML, allowing syntax highlighting and formatting to be applied. + +-+ +####
+ +####
+ +####
{content}
+ + + ); + }); + await next(); +}); +app.get("/about", (c) => { + return c.render("Hello!", { title: "Hono SSG Page" }); +}); + +export default app; +``` + +For Node.js, create a build script like this: + +```ts +import { toSSG } from "hono/ssg"; +import fs from "node:fs/promises"; + +// build.ts +import app from "./index"; + +toSSG(app, fs); +``` + +By executing the script, the files will be output as follows: + +```bash +ls ./static +about.html index.html +``` + +### Vite Plugin + +Using the `@hono/vite-ssg` Vite Plugin, you can easily handle the process. + +For more details, see here: + +https://github.com/honojs/vite-plugins/tree/main/packages/ssg + +## toSSG + +`toSSG` is the main function for generating static sites, taking an application and a filesystem module as arguments. It is based on the following: + +### Input + +The arguments for toSSG are specified in ToSSGInterface. + +```ts +export type ToSSGInterface = { + ( + app: Hono, + fsModule: FileSystemModule, + options?: ToSSGOptions + ): Promise
+
+ )
+ }
+)
+```
+
+### disableSSG
+
+Routes with the `disableSSG` middleware set are excluded from static file generation by `toSSG`.
+
+```ts
+app.get("/api", disableSSG(), c => c.text("an-api"));
+```
+
+### onlySSG
+
+Routes with the `onlySSG` middleware set will be overridden by `c.notFound()` after `toSSG` execution.
+
+```ts
+app.get('/static-page', onlySSG(), (c) => c.html({shop.name}
+Welcome to my site
)) +``` diff --git a/.cursor/rules/hono/helpers/streaming.mdc b/.cursor/rules/hono/helpers/streaming.mdc new file mode 100644 index 0000000..9bb6927 --- /dev/null +++ b/.cursor/rules/hono/helpers/streaming.mdc @@ -0,0 +1,129 @@ +--- +description: Hono Streaming helper for handling streaming responses including Server-Sent Events and real-time data streaming capabilities +globs: +alwaysApply: false +--- + +# Streaming Helper + +The Streaming Helper provides methods for streaming responses. + +## Import + +```ts +import { Hono } from "hono"; +import { stream, streamSSE, streamText } from "hono/streaming"; +``` + +## `stream()` + +It returns a simple streaming response as `Response` object. + +```ts +app.get("/stream", (c) => { + return stream(c, async (stream) => { + // Write a process to be executed when aborted. + stream.onAbort(() => { + console.log("Aborted!"); + }); + // Write a Uint8Array. + await stream.write(new Uint8Array([0x48, 0x65, 0x6C, 0x6C, 0x6F])); + // Pipe a readable stream. + await stream.pipe(anotherReadableStream); + }); +}); +``` + +## `streamText()` + +It returns a streaming response with `Content-Type:text/plain`, `Transfer-Encoding:chunked`, and `X-Content-Type-Options:nosniff` headers. + +```ts +app.get("/streamText", (c) => { + return streamText(c, async (stream) => { + // Write a text with a new line ('\n'). + await stream.writeln("Hello"); + // Wait 1 second. + await stream.sleep(1000); + // Write a text without a new line. + await stream.write(`Hono!`); + }); +}); +``` + +::: warning + +If you are developing an application for Cloudflare Workers, a streaming may not work well on Wrangler. If so, add `Identity` for `Content-Encoding` header. + +```ts +app.get("/streamText", (c) => { + c.header("Content-Encoding", "Identity"); + return streamText(c, async (stream) => { + // ... + }); +}); +``` + +::: + +## `streamSSE()` + +It allows you to stream Server-Sent Events (SSE) seamlessly. + +```ts +const app = new Hono(); +let id = 0; + +app.get("/sse", async (c) => { + return streamSSE(c, async (stream) => { + while (true) { + const message = `It is ${new Date().toISOString()}`; + await stream.writeSSE({ + data: message, + event: "time-update", + id: String(id++), + }); + await stream.sleep(1000); + } + }); +}); +``` + +## Error Handling + +The third argument of the streaming helper is an error handler. +This argument is optional, if you don't specify it, the error will be output as a console error. + +```ts +app.get("/stream", (c) => { + return stream( + c, + async (stream) => { + // Write a process to be executed when aborted. + stream.onAbort(() => { + console.log("Aborted!"); + }); + // Write a Uint8Array. + await stream.write( + new Uint8Array([0x48, 0x65, 0x6C, 0x6C, 0x6F]) + ); + // Pipe a readable stream. + await stream.pipe(anotherReadableStream); + }, + (err, stream) => { + stream.writeln("An error occurred!"); + console.error(err); + } + ); +}); +``` + +The stream will be automatically closed after the callbacks are executed. + +::: warning + +If the callback function of the streaming helper throws an error, the `onError` event of Hono will not be triggered. + +`onError` is a hook to handle errors before the response is sent and overwrite the response. However, when the callback function is executed, the stream has already started, so it cannot be overwritten. + +::: diff --git a/.cursor/rules/hono/helpers/testing.mdc b/.cursor/rules/hono/helpers/testing.mdc new file mode 100644 index 0000000..501dab3 --- /dev/null +++ b/.cursor/rules/hono/helpers/testing.mdc @@ -0,0 +1,109 @@ +--- +description: Hono Testing helper for unit testing and integration testing of Hono applications with utilities for request simulation and response validation +globs: +alwaysApply: false +--- + +# Testing Helper + +The Testing Helper provides functions to make testing of Hono applications easier. + +## Import + +```ts +import { Hono } from "hono"; +import { testClient } from "hono/testing"; +``` + +## `testClient()` + +The `testClient()` function takes an instance of Hono as its first argument and returns an object typed according to your Hono application's routes, similar to the [Hono Client](/docs/guides/rpc#client). This allows you to call your defined routes in a type-safe manner with editor autocompletion within your tests. + +**Important Note on Type Inference:** + +For the `testClient` to correctly infer the types of your routes and provide autocompletion, **you must define your routes using chained methods directly on the `Hono` instance**. + +The type inference relies on the type flowing through the chained `.get()`, `.post()`, etc., calls. If you define routes separately after creating the Hono instance (like the common pattern shown in the "Hello World" example: `const app = new Hono(); app.get(...)`), the `testClient` will not have the necessary type information for specific routes, and you won't get the type-safe client features. + +**Example:** + +This example works because the `.get()` method is chained directly onto the `new Hono()` call: + +```ts +// index.ts +const app = new Hono().get("/search", (c) => { + const query = c.req.query("q"); + return c.json({ query, results: ["result1", "result2"] }); +}); + +export default app; +``` + +```ts +// index.test.ts +import { Hono } from "hono"; +import { testClient } from "hono/testing"; +import { describe, expect, it } from "vitest"; // Or your preferred test runner + +import app from "./app"; + +describe("Search Endpoint", () => { + // Create the test client from the app instance + const client = testClient(app); + + it("should return search results", async () => { + // Call the endpoint using the typed client + // Notice the type safety for query parameters (if defined in the route) + // and the direct access via .$get() + const res = await client.search.$get({ + query: { q: "hono" }, + }); + + // Assertions + expect(res.status).toBe(200); + expect(await res.json()).toEqual({ + query: "hono", + results: ["result1", "result2"], + }); + }); +}); +``` + +To include headers in your test, pass them as the second parameter in the call. + +```ts +// index.test.ts +import { Hono } from "hono"; +import { testClient } from "hono/testing"; +import { describe, expect, it } from "vitest"; // Or your preferred test runner + +import app from "./app"; + +describe("Search Endpoint", () => { + // Create the test client from the app instance + const client = testClient(app); + + it("should return search results", async () => { + // Include the token in the headers and set the content type + const token = "this-is-a-very-clean-token"; + const res = await client.search.$get( + { + query: { q: "hono" }, + }, + { + headers: { + "Authorization": `Bearer ${token}`, + "Content-Type": `application/json`, + }, + } + ); + + // Assertions + expect(res.status).toBe(200); + expect(await res.json()).toEqual({ + query: "hono", + results: ["result1", "result2"], + }); + }); +}); +``` diff --git a/.cursor/rules/hono/helpers/websocket.mdc b/.cursor/rules/hono/helpers/websocket.mdc new file mode 100644 index 0000000..37af80a --- /dev/null +++ b/.cursor/rules/hono/helpers/websocket.mdc @@ -0,0 +1,200 @@ +--- +description: Hono WebSocket helper for implementing real-time WebSocket connections and bidirectional communication in Hono applications +globs: +alwaysApply: false +--- + +# WebSocket Helper + +WebSocket Helper is a helper for server-side WebSockets in Hono applications. +Currently Cloudflare Workers / Pages, Deno, and Bun adapters are available. + +## Import + +::: code-group + +```ts [Cloudflare Workers] +import { Hono } from "hono"; +import { upgradeWebSocket } from "hono/cloudflare-workers"; +``` + +```ts [Deno] +import { Hono } from "hono"; +import { upgradeWebSocket } from "hono/deno"; +``` + +```ts [Bun] +import type { ServerWebSocket } from "bun"; + +import { Hono } from "hono"; +import { createBunWebSocket } from "hono/bun"; + +const { upgradeWebSocket, websocket } + = createBunWebSocket{children}
+
+
+ );
+ })
+);
+
+app.get("/page/about", (c) => {
+ return c.render(About me!
); +}); +``` + +## Options + +###Hi!
;
+}
+
+app.get(
+ "*",
+ jsxRenderer(
+ ({ children }) => {
+ return (
+
+
+ SSR Streaming
+ {children} + + + ); + }, + { stream: true } + ) +); + +app.get("/", (c) => { + return c.render( +{children}
+
+ You are accessing:
+ {" "}
+
+ );
+});
+```
+
+::: warning
+You can't use `useRequestContext()` with the Deno's `precompile` JSX option. Use the `react-jsx`:
+
+```json
+ "compilerOptions": {
+ "jsx": "precompile", // [!code --]
+ "jsx": "react-jsx", // [!code ++]
+ "jsxImportSource": "hono/jsx"
+ }
+ }
+```
+
+:::
+
+## Extending `ContextRenderer`
+
+By defining `ContextRenderer` as shown below, you can pass additional content to the renderer. This is handy, for instance, when you want to change the contents of the head tag depending on the page.
+
+```tsx
+declare module "hono" {
+ type ContextRenderer = {
+ (
+ content: string | Promise{children}
+
+
+ );
+ })
+);
+
+app.get("/page/favorites", (c) => {
+ return c.render(
+
+
,
+ {
+ title: "My favorites",
+ }
+ );
+});
+```
diff --git a/.cursor/rules/hono/middleware/builtin/jwk.mdc b/.cursor/rules/hono/middleware/builtin/jwk.mdc
new file mode 100644
index 0000000..8ee7002
--- /dev/null
+++ b/.cursor/rules/hono/middleware/builtin/jwk.mdc
@@ -0,0 +1,71 @@
+---
+description: Hono JWK Auth middleware for JSON Web Key authentication using public key cryptography for secure token verification
+globs:
+alwaysApply: false
+---
+
+# JWK Auth Middleware
+
+The JWK Auth Middleware authenticates requests by verifying tokens using JWK (JSON Web Key). It checks for an `Authorization` header and other configured sources, such as cookies, if specified. Specifically, it validates tokens using the provided `keys`, retrieves keys from `jwks_uri` if specified, and supports token extraction from cookies if the `cookie` option is set.
+
+:::info
+The Authorization header sent from the client must have a specified scheme.
+
+Example: `Bearer my.token.value` or `Basic my.token.value`
+:::
+
+## Import
+
+```ts
+import { Hono } from "hono";
+import { jwk } from "hono/jwk";
+```
+
+## Usage
+
+```ts
+const app = new Hono();
+
+app.use(
+ "/auth/*",
+ jwk({
+ jwks_uri: `https://${backendServer}/.well-known/jwks.json`,
+ })
+);
+
+app.get("/auth/page", (c) => {
+ return c.text("You are authorized");
+});
+```
+
+Get payload:
+
+```ts
+const app = new Hono();
+
+app.use(
+ "/auth/*",
+ jwk({
+ jwks_uri: `https://${backendServer}/.well-known/jwks.json`,
+ })
+);
+
+app.get("/auth/page", (c) => {
+ const payload = c.get("jwtPayload");
+ return c.json(payload); // eg: { "sub": "1234567890", "name": "John Doe", "iat": 1516239022 }
+});
+```
+
+## Options
+
+### -
+
- Eating sushi +
- Watching baseball games +