React Router Hono Server Integration

Common errors

• Module 'react-router' has no exported member 'Future'.

  cause The TypeScript declaration for `Future` with `v8_middleware` flag is missing or incorrectly placed.
  fix Add the type declaration `declare module 'react-router' { interface Future { v8_middleware: true; } }` to a global TypeScript declaration file in your project.

• SyntaxError: require() of ES Module ... not supported. Instead change the require to a dynamic import() or top-level import statement.

  cause Attempting to use CommonJS `require()` to import modules from `react-router-hono-server`, which is an ESM-only package.
  fix Refactor all module imports to use ES module `import ... from '...'` syntax. Ensure your Node.js environment is configured to run ESM.

• Error: [plugin:react-router-hono-server] Server entry point not found. Please provide one or use the default 'server.ts' or 'server/index.ts'.

  cause The Vite plugin could not locate a server entry file as per its default conventions or a specified `serverEntryPoint` option.
  fix Create a `server.ts` file in your application's root directory, or specify the correct path to your server entry file using the `serverEntryPoint` option in `reactRouterHonoServer({ serverEntryPoint: './src/my-server-entry.ts' })` in `vite.config.ts`.

• Error: Cannot find module 'hono' or Error: 'hono' is not found in the root dependency tree.

  cause The `hono` peer dependency is not correctly installed or linked, often due to package manager strictness (e.g., pnpm).
  fix Ensure `hono` is explicitly installed in your project (`npm install hono` or `yarn add hono`). If using pnpm, add `public-hoist-pattern[]=hono` to your `.npmrc` file.

Warnings

• breaking This package is strictly compatible only with React Router v7. It is not compatible with previous versions (e.g., Remix or older React Router versions).
  Fix: Ensure your project uses React Router v7. If migrating from v1, consult the migration guide in the package's GitHub repository.
• breaking The library is ESM-only. CommonJS (CJS) `require()` statements are not supported for importing any modules from this package.
  Fix: Always use `import ... from '...'` syntax. Ensure your project is configured for ESM, including `type: 'module'` in `package.json` if running in Node.js.
• gotcha For correct TypeScript typings, especially when using React Router's middleware, you must declare `v8_middleware: true` in the `Future` interface of the `react-router` module.
  Fix: Add `declare module 'react-router' { interface Future { v8_middleware: true; } }` to a TypeScript declaration file (e.g., `react-router.config.ts` or `src/globals.d.ts`).
• gotcha The `hono` package is a peer dependency. If using pnpm, you might encounter issues with `hono` not being found due to pnpm's strict dependency linking.
  Fix: Manually install `hono` or add `public-hoist-pattern[]=hono` to your `.npmrc` file if using pnpm to ensure it's hoisted and discoverable.
• gotcha The `react-router-hono-server/dev` Vite plugin is required for development, HMR, and to trigger the server build process.
  Fix: Ensure `reactRouterHonoServer()` is included in the `plugins` array of your `vite.config.ts`.
• gotcha By default, the plugin looks for a server entry point at `${appDirectory}/server.ts` or in a folder named `${appDirectory}/server`. These paths are reserved unless a custom `serverEntryPoint` is explicitly configured in the plugin options.
  Fix: Either use the default naming convention (`server.ts`) or specify your custom server entry point via `reactRouterHonoServer({ serverEntryPoint: './path/to/your/server.ts' })`.

Install

• npm install react-router-hono-server npm
• yarn add react-router-hono-server yarn
• pnpm add react-router-hono-server pnpm

Imports

• reactRouterHonoServer
  wrong:

  const reactRouterHonoServer = require('react-router-hono-server/dev');

  correct:

  import { reactRouterHonoServer } from 'react-router-hono-server/dev';

  This is the Vite plugin entry point, used in `vite.config.ts`. The library is ESM-only.
• createHonoServer
  wrong:

  import { createHonoServer } from 'react-router-hono-server';

  correct:

  import { createHonoServer } from 'react-router-hono-server/node';

  The `createHonoServer` function is runtime-specific; use `/node` for Node.js environments. Other entry points may exist for Bun/Workers.
• Future

  declare module 'react-router' { interface Future { v8_middleware: true; } }

  This is a type declaration, not a runtime import. It's crucial for enabling correct TypeScript typings for React Router v8 middleware flags when using this library.

Quickstart

This shows how to integrate the `react-router-hono-server/dev` Vite plugin into your `vite.config.ts` to automatically generate a default Hono server for your React Router application, enabling HMR and production builds.

import { reactRouter } from "@react-router/dev/vite";
import { reactRouterHonoServer } from "react-router-hono-server/dev";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  plugins: [
    reactRouterHonoServer(), // Add this plugin to enable Hono server integration
    reactRouter(), // Required React Router Dev plugin
    tsconfigPaths()
  ],
  // Optional: Configure build outputs for server (e.g., for Cloudflare Workers)
  // build: {
  //   rollupOptions: {
  //     output: {
  //       entryFileNames: '[name].js',
  //       chunkFileNames: '[name]-[hash].js',
  //       assetFileNames: '[name].[ext]'
  //     }
  //   }
  // }
});

// This minimal setup automatically generates a default Hono server.
// For custom server logic, create a 'server.ts' file at your app's root
// or configure the 'serverEntryPoint' option in reactRouterHonoServer().