{"id":11846,"library":"react-router-hono-server","title":"React Router Hono Server Integration","description":"react-router-hono-server is a JavaScript/TypeScript library designed to integrate React Router v7 applications with Hono servers, primarily through a Vite plugin. It simplifies the setup of server-side rendering (SSR) and middleware for React Router, enabling development with Vite's Hot Module Replacement (HMR). The library is currently at version 2.25.3, with a release cadence that frequently updates to align with new versions of Hono and React Router. Its key differentiators include native support for React Router v7's unstable middleware API, broad deployment target compatibility (Node, Bun, Cloudflare Workers, AWS Lambda), and an opinionated but customizable default Hono server configuration. It strictly operates in ESM mode and leverages Vite for its build and development pipeline. The package relies on peer dependencies like `hono`, `react-router`, and `@hono/node-server` to function.","status":"active","version":"2.25.3","language":"javascript","source_language":"en","source_url":"https://github.com/rphlmr/react-router-hono-server","tags":["javascript"],"install":[{"cmd":"npm install react-router-hono-server","lang":"bash","label":"npm"},{"cmd":"yarn add react-router-hono-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-router-hono-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Cloudflare Workers deployment targets.","package":"@cloudflare/workers-types","optional":true},{"reason":"Runtime server adapter for Node.js environments. Can be a dev dependency for Bun.","package":"@hono/node-server","optional":false},{"reason":"Peer dependency for the React Router Vite plugin, which is used by this package's Vite plugin.","package":"@react-router/dev","optional":false},{"reason":"Peer dependency for React type definitions.","package":"@types/react","optional":false},{"reason":"Core Hono framework dependency for server creation and middleware.","package":"hono","optional":false},{"reason":"Required for local development and testing with Cloudflare Workers.","package":"miniflare","optional":true},{"reason":"Core peer dependency for React Router v7 functionality.","package":"react-router","optional":false},{"reason":"Core peer dependency as it integrates directly with Vite build and development processes.","package":"vite","optional":false},{"reason":"Required for deploying to Cloudflare Workers.","package":"wrangler","optional":true}],"imports":[{"note":"This is the Vite plugin entry point, used in `vite.config.ts`. The library is ESM-only.","wrong":"const reactRouterHonoServer = require('react-router-hono-server/dev');","symbol":"reactRouterHonoServer","correct":"import { reactRouterHonoServer } from 'react-router-hono-server/dev';"},{"note":"The `createHonoServer` function is runtime-specific; use `/node` for Node.js environments. Other entry points may exist for Bun/Workers.","wrong":"import { createHonoServer } from 'react-router-hono-server';","symbol":"createHonoServer","correct":"import { createHonoServer } from 'react-router-hono-server/node';"},{"note":"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.","symbol":"Future","correct":"declare module 'react-router' { interface Future { v8_middleware: true; } }"}],"quickstart":{"code":"import { reactRouter } from \"@react-router/dev/vite\";\nimport { reactRouterHonoServer } from \"react-router-hono-server/dev\";\nimport { defineConfig } from \"vite\";\nimport tsconfigPaths from \"vite-tsconfig-paths\";\n\nexport default defineConfig({\n  plugins: [\n    reactRouterHonoServer(), // Add this plugin to enable Hono server integration\n    reactRouter(), // Required React Router Dev plugin\n    tsconfigPaths()\n  ],\n  // Optional: Configure build outputs for server (e.g., for Cloudflare Workers)\n  // build: {\n  //   rollupOptions: {\n  //     output: {\n  //       entryFileNames: '[name].js',\n  //       chunkFileNames: '[name]-[hash].js',\n  //       assetFileNames: '[name].[ext]'\n  //     }\n  //   }\n  // }\n});\n\n// This minimal setup automatically generates a default Hono server.\n// For custom server logic, create a 'server.ts' file at your app's root\n// or configure the 'serverEntryPoint' option in reactRouterHonoServer().","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure your project uses React Router v7. If migrating from v1, consult the migration guide in the package's GitHub repository.","message":"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).","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always use `import ... from '...'` syntax. Ensure your project is configured for ESM, including `type: 'module'` in `package.json` if running in Node.js.","message":"The library is ESM-only. CommonJS (CJS) `require()` statements are not supported for importing any modules from this package.","severity":"breaking","affected_versions":">=2.0.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=2.22.0"},{"fix":"Manually install `hono` or add `public-hoist-pattern[]=hono` to your `.npmrc` file if using pnpm to ensure it's hoisted and discoverable.","message":"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. ","severity":"gotcha","affected_versions":">=2.24.1"},{"fix":"Ensure `reactRouterHonoServer()` is included in the `plugins` array of your `vite.config.ts`.","message":"The `react-router-hono-server/dev` Vite plugin is required for development, HMR, and to trigger the server build process.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Either use the default naming convention (`server.ts`) or specify your custom server entry point via `reactRouterHonoServer({ serverEntryPoint: './path/to/your/server.ts' })`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add the type declaration `declare module 'react-router' { interface Future { v8_middleware: true; } }` to a global TypeScript declaration file in your project.","cause":"The TypeScript declaration for `Future` with `v8_middleware` flag is missing or incorrectly placed.","error":"Module 'react-router' has no exported member 'Future'."},{"fix":"Refactor all module imports to use ES module `import ... from '...'` syntax. Ensure your Node.js environment is configured to run ESM.","cause":"Attempting to use CommonJS `require()` to import modules from `react-router-hono-server`, which is an ESM-only package.","error":"SyntaxError: require() of ES Module ... not supported. Instead change the require to a dynamic import() or top-level import statement."},{"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`.","cause":"The Vite plugin could not locate a server entry file as per its default conventions or a specified `serverEntryPoint` option.","error":"Error: [plugin:react-router-hono-server] Server entry point not found. Please provide one or use the default 'server.ts' or 'server/index.ts'."},{"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.","cause":"The `hono` peer dependency is not correctly installed or linked, often due to package manager strictness (e.g., pnpm).","error":"Error: Cannot find module 'hono' or Error: 'hono' is not found in the root dependency tree."}],"ecosystem":"npm"}