React Router + Hono + Cloudflare　のテンプレートを作る

publication: 2025/09/03

update:2025/09/11

React Router のテンプレート

React Router では Cloudflare 用の公式のテンプレートが用意されています。しかし Hono を含んだテンプレートがないため、今回、用意しました。

https://github.com/SoraKumo001/react-router-templates

使い方

使い方は基本的に公式のテンプレートと同じです。

1npx create-react-router@latest --template sorakumo001/react-router-templates/cloudflare

公式のテンプレートとの違い

こちらが公式テンプレートです

https://github.com/remix-run/react-router-templates/tree/main/cloudflare

Middleware として Hono を導入

React Router の Middleware はまだ開発段階なので、現時点では Hono を使ったほうが無難です。

@cloudflare/vite-pluginを除去

@cloudflare/vite-pluginを使うと、開発時に Cloudflare 環境の再現性が高まるのですが、外部モジュールの初期インポートに時間がかかるので、依存モジュールが増えていくと辛くなっていきます。また、rolldown-viteとの併用ができないため、今回は取り除きました。

rolldown-viteの導入

rolldown-viteを使うと、ビルド速度が半分以下に短縮されます。圧倒的な速度です。

カスタマイズ部分の解説

vite.config.ts

Hono が使えるように設定しています。ただし Hono の Cloudflare 用の Adapter を直接使わず、処理を修正しています。理由として元の Adapter は navigator.userAgent の値を偽装する処理が入っているため、Prisma の queryCompiler の機能を使おうと思った場合に、環境の識別ができず正常に動作しなくなるためです。

また、開発実行時と Deploy 時で、起動コードを共通化するためにvirtual:react-router/server-buildをエイリアスで切り替えています。@cloudflare/vite-pluginを使った場合は、別の方法で起動コードの自動切り替えが行われるのですが今回未使用のため、この設定を入れています。

svg など import 系の Assets に関しては、利用するものを適宜指定する必要があります。足りないものは exclude で追加指定してください。これをやらないと、開発時に対象のファイルが表示されません。

handleHotUpdate でサーバ側でのみ動作するファイルのみフルリロードするようにしています。これを入れないと、@hono/vite-dev-serverのデフォルト動作で、どのファイルを更新してもフルリロードされます。

1import { reactRouter } from "@react-router/dev/vite";
2import tailwindcss from "@tailwindcss/vite";
3import serverAdapter, { defaultOptions } from "@hono/vite-dev-server";
4import type { cloudflareAdapter } from "@hono/vite-dev-server/cloudflare";
5import { defineConfig } from "vite";
6import tsconfigPaths from "vite-tsconfig-paths";
7import { getPlatformProxy, unstable_getVarsForDev } from "wrangler";
8
9// Entry file
10const entry = "./workers/app.ts";
11
12// Prevent tampering with Hono's Cloudflare parameters executed by default
13const adapter: typeof cloudflareAdapter = async (options) => {
14  const proxy = await getPlatformProxy(options?.proxy);
15  return {
16    env: proxy.env,
17    executionContext: proxy.ctx,
18    onServerClose: () => proxy.dispose(),
19  };
20};
21
22export default defineConfig({
23  resolve: {
24    alias: [
25      {
26        find: "../build/server/index.js",
27        replacement: "virtual:react-router/server-build",
28      },
29    ],
30  },
31  ssr: {
32    resolve: {
33      externalConditions: ["worker"],
34    },
35  },
36  plugins: [
37    serverAdapter({
38      adapter,
39      entry,
40      // Asset adjustment
41      exclude: [...defaultOptions.exclude, /\.(webp|png|svg)(\?.*)?$/],
42      // HMR adjustment
43      handleHotUpdate: ({ server, modules }) => {
44        const isServer = modules.some((mod) => {
45          return mod._ssrModule?.id && !mod._clientModule;
46        });
47        if (isServer) {
48          server.hot.send({ type: "full-reload" });
49          return [];
50        }
51      },
52    }),
53    tailwindcss(),
54    reactRouter(),
55    tsconfigPaths(),
56  ],
57  experimental: { enableNativePlugin: true },
58});

workers/app.ts

起動コードです。Hono を使って、React Router を呼び出しています。前述した通り../build/server/index.jsは、Vite からはvirtual:react-router/server-buildに変換され、deploy などでwranglerから呼び出されるときは変換せずに使われます。

1import { Hono } from "hono";
2import { contextStorage } from "hono/context-storage";
3import { getLoadContext } from "load-context";
4import { createRequestHandler } from "react-router";
5
6const app = new Hono();
7app.use(contextStorage());
8
9app.use(async (c) => {
10  // @ts-ignore
11  const build = await import("../build/server/index.js");
12  // @ts-ignore
13  const handler = createRequestHandler(build, import.meta.env?.MODE);
14
15  const next = (input: Request | string, init?: RequestInit) => {
16    return handler(new Request(input, init), {
17      cloudflare: { env: c.env },
18    });
19  };
20  const context = getLoadContext({
21    request: c.req.raw,
22    context: {
23      cloudflare: {
24        env: c.env,
25        next,
26      },
27    } as never,
28  });
29  return handler(c.req.raw, context);
30});
31
32export default app;

.env

NODE_ENV を production に設定しています。これがなんの為にあるのかというと、wrangler deploy時に必要だからです。wranglerは、バックエンド側のコードを esbuild でビルドします。そして環境変数が設定されていないと node_module に含まれている react が、デバッグ用の開発パッケージをビルドに加えてしまい、性能の低下やサイズの増加を引き起こします。フロント側は影響を受けませんが、バックエンド側ではこの問題が発生します。

これ、結構重大な問題なのですが、巷のリポジトリを覗いてみても、だれも対処していません。

1# If this configuration is missing during `wrangler deploy`, the React development module will be used.
2NODE_ENV=production

まとめ

React RouterはNext.jsと比べると、初期設定の選択肢が多いため、それがハードルになっている感があります。ただ、Cloudflare 用の React 用フレームワークと考えた場合、他に選択肢がありません。Next.jsをopennextから使うという手を思いつくかもしれませんが、ビルドで吐き出されるサイズが巨大すぎてはっきり言って問題外です。

公式のテンプレートは@cloudflare/vite-pluginを使ったものになっており、本番に近い環境をエミュレーションして開発できる反面、モジュールの読み込みにクセがあります。依存パッケージによっては、開発が難しくなる場合があります。原理を話すと長くなるのですが、エミュレーション環境であるworkerdでモジュールのやりとりをするとき、ESM しか対応していないので、node_modules の魑魅魍魎なパッケージ群をうまく変換しながら渡す必要があります。ビルド時は全体を一括でまとめて変換できるのでよいのですが、開発時は部分的にビルドしながら渡していかねばならず、このときにモジュールの整合性をとる作業が破滅的に複雑です。そのため、@cloudflare/vite-pluginを使った場合、依存パッケージが増えるに従いどんどん動作が重くなっていきます。

ということで、あえて@cloudflare/vite-pluginを外したテンプレートを作りました。開発時の再現性は劣りますが、快適性は圧倒的に良くなっています。公式テンプレートで、依存パッケージの問題で苦労している人は使ってみてください。

React Router + Hono + Cloudflare のテンプレートを作る