hono-remix-adapter

hono-remix-adapter is a set of tools for adapting between Hono and Remix. It is composed of a Vite plugin and handlers that enable it to support platforms like Cloudflare Workers. You can create an Hono app, and it will be applied to your Remix app.

// server/index.ts
import { Hono } from 'hono'

const app = new Hono()

app.use(async (c, next) => {
  await next()
  c.header('X-Powered-By', 'Remix and Hono')
})

app.get('/api', (c) => {
  return c.json({
    message: 'Hello',
  })
})

export default app

This means you can create API routes with Hono's syntax and use a lot of Hono's built-in middleware and third-party middleware.

[!WARNING]

hono-remix-adapter is currently unstable. The API may be changed without announcement in the future.

Install

npm i hono-remix-adapter

How to use

Edit your vite.config.ts:

// vite.config.ts
import serverAdapter from 'hono-remix-adapter/vite'

export default defineConfig({
  plugins: [
    // ...
    remix(),
    serverAdapter({
      entry: 'server/index.ts',
    }),
  ],
})

Write your Hono app:

// server/index.ts
import { Hono } from 'hono'

const app = new Hono()

//...

export default app

Cloudflare Workers

To support Cloudflare Workers and Cloudflare Pages, add the adapter in @hono/vite-dev-server for development.

// vite.config.ts
import adapter from '@hono/vite-dev-server/cloudflare'
import serverAdapter from 'hono-remix-adapter/vite'

export default defineConfig({
  plugins: [
    // ...
    remix(),
    serverAdapter({
      adapter, // Add Cloudflare adapter
      entry: 'server/index.ts',
    }),
  ],
})

To deploy your app to Cloudflare Workers, you can write the following handler on worker.ts:

// worker.ts
import handle from 'hono-remix-adapter/cloudflare-workers'
import * as build from './build/server'
import server from './server'

export default handle(build, server)

Specify worker.ts in your wrangler.toml:

name = "example-cloudflare-workers"
compatibility_date = "2024-11-06"
main = "./worker.ts"
assets = { directory = "./build/client" }

Cloudflare Pages

To deploy your app to Cloudflare Pages, you can write the following handler on functions/[[path]].ts:

// functions/[[path]].ts
import handle from 'hono-remix-adapter/cloudflare-pages'
import * as build from '../build/server'
import server from '../server'

export const onRequest = handle(build, server)

getLoadContext

If you want to add extra context values when you use Remix routes, like in the following use case:

// app/routes/_index.tsx
import type { LoaderFunctionArgs } from '@remix-run/cloudflare'
import { useLoaderData } from '@remix-run/react'

export const loader = ({ context }) => {
  return { extra: context.extra }
}

export default function Index() {
  const { extra } = useLoaderData<typeof loader>()
  return <h1>Extra is {extra}</h1>
}

First, create the getLoadContext function and export it:

// load-context.ts
import type { AppLoadContext } from '@remix-run/cloudflare'
import type { PlatformProxy } from 'wrangler'

type Cloudflare = Omit<PlatformProxy, 'dispose'>

declare module '@remix-run/cloudflare' {
  interface AppLoadContext {
    cloudflare: Cloudflare
    extra: string
  }
}

type GetLoadContext = (args: {
  request: Request
  context: { cloudflare: Cloudflare }
}) => AppLoadContext

export const getLoadContext: GetLoadContext = ({ context }) => {
  return {
    ...context,
    extra: 'stuff',
  }
}

Then import the getLoadContext and add it to the serverAdapter as an argument in your vite.config.ts:

// vite.config.ts
import adapter from '@hono/vite-dev-server/cloudflare'
import { vitePlugin as remix } from '@remix-run/dev'
import serverAdapter from 'hono-remix-adapter/vite'
import { defineConfig } from 'vite'
import { getLoadContext } from './load-context'

export default defineConfig({
  plugins: [
    // ...
    remix(),
    serverAdapter({
      adapter,
      getLoadContext,
      entry: 'server/index.ts',
    }),
  ],
})

For Cloudflare Workers, you can add it to the handler function:

// worker.ts
import handle from 'hono-remix-adapter/cloudflare-workers'
import * as build from './build/server'
import { getLoadContext } from './load-context'
import app from './server'

export default handle(build, app, { getLoadContext })

You can also add it for Cloudflare Pages:

// functions/[[path]].ts
import handle from 'hono-remix-adapter/cloudflare-pages'
import { getLoadContext } from 'load-context'
import * as build from '../build/server'
import server from '../server'

export const onRequest = handle(build, server, { getLoadContext })

This way is almost the same as Remix.

Auth middleware for Remix routes

If you want to add Auth Middleware, e.g. Basic Auth middleware, please be careful that users can access the protected pages with SPA tradition. To prevent this, add a loader to the page:

// app/routes/admin
export const loader = async () => {
  return { props: {} }
}

Related works

• https://github.com/sergiodxa/remix-hono
• https://github.com/yusukebe/hono-and-remix-on-vite

Author

Yusuke Wada https://github.com/yusukebe

License

MIT