hono/docs/MIGRATION.md

Migration Guide

v4.3.11 to v4.4.0

deno.land/x to JSR

There is no braking change, but we no longer publish the module from deno.land/x. If you want to use Hono on Deno, use JSR instead of it.

If you migrate, replace the path deno.land/x with JSR's.

// From
import { Hono } from 'https://deno.land/x/hono/mod.ts'

// To
import { Hono } from 'jsr:@hono/hono'

You can see more details on our website: https://hono.dev/getting-started/deno

v3.12.x to v4.0.0

There are some breaking changes.

Removal of deprecated features

• AWS Lambda Adapter - LambdaFunctionUrlRequestContext is obsolete. Use ApiGatewayRequestContextV2 instead.
• Next.js Adapter - hono/nextjs is obsolete. Use hono/vercel instead.
• Context - c.jsonT() is obsolete. Use c.json() instead.
• Context - c.stream() and c.streamText() are obsolete. Use stream() and streamText() in hono/streaming instead.
• Context - c.env() is obsolete. Use getRuntimeKey() in hono/adapter instead.
• Hono - app.showRoutes() is obsolete. Use showRoutes() in hono/dev instead.
• Hono - app.routerName is obsolete. Use getRouterName() in hono/dev instead.
• Hono - app.head() is no longer used. app.get() implicitly handles the HEAD method.
• Hono - app.handleEvent() is obsolete. Use app.fetch() instead.
• HonoRequest - req.cookie() is obsolete. Use getCookie() in hono/cookie instead.
• HonoRequest - headers(), body(), bodyUsed(), integrity(), keepalive(), referrer(), and signal() are obsolete. Use the methods in req.raw such as req.raw.headers().

serveStatic in Cloudflare Workers Adapter requires manifest

If you use the Cloudflare Workers adapter's serve-static, you should specify the manifest option.

import manifest from '__STATIC_CONTENT_MANIFEST'

// ...

app.use('/static/*', serveStatic({ root: './assets', manifest }))

Others

• The default value of docType option in JSX Renderer Middleware is now true.
• FC in hono/jsx does not pass children. Use PropsWithChildren.
• Some Mime Types are removed https://github.com/honojs/hono/pull/2119.
• Types for chaining routes with middleware matter: https://github.com/honojs/hono/pull/2046.
• Types for the validator matter: https://github.com/honojs/hono/pull/2130.

v2.7.8 to v3.0.0

There are some breaking changes. In addition to the following, type mismatches may occur.

c.req is now HonoRequest

c.req becomes HonoRequest, not Request. Although APIs are almost same, but if you want to access Request, use c.req.raw.

app.post('/', async (c) => {
  const metadata = c.req.raw.cf?.hostMetadata?
  ...
})

StaticRouter is obsolete

You can't use StaticRouter.

Validator is changed

Previous Validator Middleware is obsolete. You can still use hono/validator, but the API has been changed. See the document.

serveStatic is provided from Adapter

Serve Static Middleware is obsolete. Use Adapters instead.

// For Cloudflare Workers
import { serveStatic } from 'hono/cloudflare-workers'

// For Bun
// import { serveStatic } from 'hono/bun'

// For Deno
// import { serveStatic } from 'npm:hono/deno'

// ...

app.get('/static/*', serveStatic({ root: './' }))

serveStatic for Cloudflare Workers "Service Worker mode" is obsolete

For Cloudflare Workers, the serveStatic is obsolete in Service Worker mode.

Note: Service Worker mode is that using app.fire(). We recommend use "Module Worker" mode with export default app.

Use type to define the Generics for new Hono

You must use type to define the Generics for new Hono. Do not use interface.

// Should use `type`
type Bindings = {
  TOKEN: string
}

const app = new Hono<{ Bindings: Bindings }>()

v2.7.1 - v2.x.x

Current Validator Middleware is deprecated

At the next major version, Validator Middleware will be changed with "breaking changes". Therefore, the current Validator Middleware will be deprecated; please use 3rd-party Validator libraries such as Zod or TypeBox.

import { z } from 'zod'

//...

const schema = z.object({
  title: z.string().max(100),
})

app.post('/posts', async (c) => {
  const body = await c.req.parseBody()
  const res = schema.safeParse(body)
  if (!res.success) {
    return c.text('Invalid!', 400)
  }
  return c.text('Valid!')
})

v2.2.5 to v2.3.0

There is a breaking change associated to the security update.

Basic Auth Middleware and Bearer Auth Middleware

If you are using Basic Auth and Bearer Auth in your Handler (nested), change as follows:

app.use('/auth/*', async (c, next) => {
  const auth = basicAuth({ username: c.env.USERNAME, password: c.env.PASSWORD })
  return auth(c, next) // Older: `await auth(c, next)`
})

v2.0.9 to v2.1.0

There are two BREAKING CHANGES.

c.req.parseBody does not parse JSON, text, and ArrayBuffer

DO NOT use c.req.parseBody for parsing JSON, text, or ArrayBuffer.

c.req.parseBody now only parses FormData with content type multipart/form or application/x-www-form-urlencoded. If you want to parse JSON, text, or ArrayBuffer, use c.req.json(), c.req.text(), or c.req.arrayBuffer().

// `multipart/form` or `application/x-www-form-urlencoded`
const data = await c.req.parseBody()

const jsonData = await c.req.json() // for JSON body
const text = await c.req.text() // for text body
const arrayBuffer = await c.req.arrayBuffer() // for ArrayBuffer

The arguments of Generics for new Hono have been changed

Now, the constructor of "Hono" receives Variables and Bindings. "Bindings" is for types of environment variables for Cloudflare Workers. "Variables" is for types of c.set/c.get

type Bindings = {
  KV: KVNamespace
  Storage: R2Bucket
}

type WebClient = {
  user: string
  pass: string
}

type Variables = {
  client: WebClient
}

const app = new Hono<{ Variables: Variables; Bindings: Bindings }>()

app.get('/foo', (c) => {
  const client = c.get('client') // client is WebClient
  const kv = c.env.KV // kv is KVNamespace
  //...
})

v1.6.4 to v2.0.0

There are many BREAKING CHANGES. Please follow instructions below.

The way to import Middleware on Deno has been changed

DO NOT import middleware from hono/mod.ts.

import { Hono, poweredBy } from 'https://deno.land/x/hono/mod.ts' // <--- NG

hono/mod.ts does not export middleware. To import middleware, use hono/middleware.ts:

import { Hono } from 'https://deno.land/x/hono/mod.ts'
import { poweredBy, basicAuth } from 'https://deno.land/x/hono/middleware.ts'

Cookie middleware is obsolete

DO NOT use cookie middleware.

import { cookie } from 'hono/cookie' // <--- Obsolete!

You do not have to use Cookie middleware to parse or set cookies. They become default functions:

// Parse cookie
app.get('/entry/:id', (c) => {
  const value = c.req.cookie('name')
  ...
})

app.get('/', (c) => {
  c.cookie('delicious_cookie', 'choco')
  return c.text('Do you like cookie?')
})

Body parse middleware is obsolete

DO NOT use body-parse middleware.

import { bodyParse } from 'hono/body-parse' // <--- Obsolete!

You do not have to use Body parse middleware to parse request body. Use c.req.parseBody() method instead.

// Parse Request body
 app.post('', (c) => {
   const body = c.req.parseBody()
   ...
 })

GraphQL Server middleware is obsolete

DO NOT use graphql-server middleware.

import { graphqlServer } from 'hono/graphql-server' // <--- Obsolete!

It might be distributed as third-party middleware.

Mustache middleware is obsolete

DO NOT use mustache middleware.

import { mustache } from 'hono/mustache' // <--- Obsolete!

It will no longer be implemented.