Agent Skills: Hono 4.8+ Knowledge Patch

Hono 4.8+ Knowledge Patch

Claude's baseline knowledge covers Hono through 4.7. This skill provides features from 4.8 (June 2025) onwards.

Reference Index

• RPC Client & Types — parseResponse, $path, typed URLs, ApplyGlobalResponse, PickResponseByStatusCode, custom NotFoundResponse, buildSearchParams
• Middleware — MCP middleware, UA blocker, JWT/JWK alg required, JWT iss/headerName, CORS dynamic methods, JWK allow_anon, Cache cacheableStatusCodes, Basic Auth onAuthSuccess
• Utilities & Runtime — Route helper (hono/route), cloneRawRequest, tryGetContext, cookie string generators, getBunServer, service worker fire(), getConnInfo for new platforms
• JSX & SSG — Streaming nonce for CSP, jsxRenderer function-based options, SSG plugin system

Quick Reference

RPC Client Essentials

| Feature | Import | Since | |---------|--------|-------| | $path() — get path string (not URL) | hono/client | 4.12 | | parseResponse() — auto content-type handling | hono/client | 4.9 | | ApplyGlobalResponse — add error types to all routes | hono/client | 4.12 | | PickResponseByStatusCode — extract status type | hono/client | 4.12 | | Typed URL via second type param on hc | hono/client | 4.11 | | buildSearchParams option on hc | hono/client | 4.11 |

// $path — returns path string, not full URL
const client = hc<typeof app>('http://localhost:8787')
client.api.posts.$path()                                // '/api/posts'
client.api.posts[':id'].$path({ param: { id: '123' } }) // '/api/posts/123'

// parseResponse — structured error handling
import { parseResponse, DetailedError } from 'hono/client'
const result = await parseResponse(client.hello.$get()).catch((e: DetailedError) => {
  console.error(e.status, e.message)
})

// ApplyGlobalResponse — type app.onError() responses into client
import { hc, ApplyGlobalResponse } from 'hono/client'
type AppWithErrors = ApplyGlobalResponse<typeof app, {
  401: { json: { error: string } }
  500: { json: { error: string } }
}>
const client = hc<AppWithErrors>('http://api.example.com')

JWT/JWK — alg Now Required (4.11.4, Security Fix)

Algorithm confusion vulnerability fixed. Always specify alg:

import { jwt } from 'hono/jwt'
app.use('/auth/*', jwt({ secret: 'my-secret', alg: 'HS256' }))

import { jwk } from 'hono/jwk'
app.use('/auth/*', jwk({ jwks_uri: '...', alg: ['RS256'] }))

MCP Middleware (@hono/mcp, 4.8+)

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StreamableHTTPTransport } from '@hono/mcp'

const mcpServer = new McpServer({ name: 'my-server', version: '1.0.0' })
app.all('/mcp', async (c) => {
  const transport = new StreamableHTTPTransport()
  await mcpServer.connect(transport)
  return transport.handleRequest(c)
})

Route Introspection (hono/route, 4.8+)

import { matchedRoutes, routePath, baseRoutePath, basePath } from 'hono/route'
app.get('/users/:id', (c) => {
  const matched = matchedRoutes(c) // Array of matched route handlers
  const current = routePath(c)     // Full resolved path
})

Utility Helpers

// cloneRawRequest — clone after body consumed (4.10+)
import { cloneRawRequest } from 'hono/request'
const cloned = cloneRawRequest(c.req) // body intact

// tryGetContext — non-throwing getContext (4.11+)
import { tryGetContext } from 'hono/context-storage'
const ctx = tryGetContext<Env>() // undefined if no context

// Cookie string generators (4.9+)
import { generateCookie, generateSignedCookie } from 'hono/cookie'
const str = generateCookie('name', 'value', { path: '/', secure: true })

UA Blocker (@hono/ua-blocker, 4.8+)

import { uaBlocker } from '@hono/ua-blocker'
import { aiBots } from '@hono/ua-blocker/ai-bots'
app.use('*', uaBlocker({ blocklist: aiBots }))

Typed URL & NotFoundResponse (4.11+)

// Typed URL — second type param gives full URL type (useful for SWR cache keys)
const client = hc<typeof app, 'http://localhost:8787'>('http://localhost:8787/')
const url = client.api.posts.$url() // TypedURL with protocol + host + path

// Custom NotFoundResponse — type c.notFound() for RPC client
declare module 'hono' {
  interface NotFoundResponse extends Response,
    TypedResponse<{ error: string }, 404, 'json'> {}
}

SSG Plugin System (4.8+)

import type { SSGPlugin } from 'hono/ssg'
const myPlugin: SSGPlugin = {
  afterGenerateHook: (result, fsModule, options) => { /* ... */ }
}
toSSG(app, fs, { plugins: [myPlugin] })

JSX Streaming Nonce (4.8+)

import { StreamingContext } from 'hono/jsx/streaming'
<StreamingContext value={{ scriptNonce: 'random-nonce' }}>
  <Suspense fallback={<div>Loading...</div>}><AsyncComponent /></Suspense>
</StreamingContext>

New Middleware Options

| Middleware | Option | Since | |-----------|--------|-------| | JWT | headerName — read from custom header | 4.8 | | JWT | issuer — validate iss claim | 4.9 | | JWT/JWK | alg — required | 4.11.4 | | CORS | allowMethods as (origin) => string[] | 4.8 | | JWK | allow_anon: true — pass unauthenticated | 4.8 | | Cache | cacheableStatusCodes array | 4.8 | | Basic Auth | onAuthSuccess callback | 4.12 |

Platform getConnInfo (4.12+)

import { handle, getConnInfo } from 'hono/aws-lambda'
import { handle, getConnInfo } from 'hono/cloudflare-pages'
import { handle, getConnInfo } from 'hono/netlify'

Breaking/Notable Changes

| Change | Since | |--------|-------| | app.fire() deprecated → use fire() from hono/service-worker | 4.8 | | JWT/JWK alg option now required (security fix) | 4.11.4 | | getBunServer export from hono/bun | 4.11.6 |