react-router.config.ts

Application configuration for React Router Framework Mode

react-router.config.ts

Configures React Router application settings. Located at react-router.config.ts in your project root.

Import

import type { Config } from "@react-router/dev/config";

ReactRouterConfig Type

export interface ReactRouterConfig {
  appDirectory?: string;
  basename?: string;
  buildDirectory?: string;
  buildEnd?: BuildEndHook;
  future?: Partial<FutureConfig>;
  prerender?: PrerenderConfig;
  presets?: Preset[];
  routeDiscovery?: RouteDiscoveryConfig;
  serverBuildFile?: string;
  serverBundles?: ServerBundlesFunction;
  serverModuleFormat?: "esm" | "cjs";
  ssr?: boolean;
  allowedActionOrigins?: string[];
}

Configuration Options

appDirectory

appDirectory · string · default: "app"

Path to the application directory, relative to project root.

export default {
  appDirectory: "src",
};

basename

basename · string · default: "/"

Base path for all routes. Useful when your app is served from a subdirectory.

export default {
  basename: "/my-app",
};

Must match Vite’s base config:

export default defineConfig({
  base: "/my-app",
  plugins: [reactRouter()],
});

buildDirectory

buildDirectory · string · default: "build"

Path to the build output directory, relative to project root.

export default {
  buildDirectory: "dist",
};

Output structure:

dist/
├── client/      # Client assets
└── server/      # Server bundle(s)

buildEnd

buildEnd · function

Hook called after build completes. Useful for custom post-build tasks.

type BuildEndHook = (args: {
  buildManifest: BuildManifest | undefined;
  reactRouterConfig: ResolvedReactRouterConfig;
  viteConfig: ResolvedConfig;
}) => void | Promise<void>;

Example:

export default {
  async buildEnd({ buildManifest, viteConfig }) {
    // Generate custom manifest
    await writeFile(
      "build/custom-manifest.json",
      JSON.stringify(buildManifest)
    );
    
    // Copy additional files
    await cp("public", "build/client/public", { recursive: true });
  },
};

future

future · object

Enables future features and breaking changes.

interface FutureConfig {
  unstable_optimizeDeps: boolean;
  unstable_subResourceIntegrity: boolean;
  unstable_trailingSlashAwareDataRequests: boolean;
  unstable_previewServerPrerendering: boolean;
  v8_middleware: boolean;
  v8_splitRouteModules: boolean | "enforce";
  v8_viteEnvironmentApi: boolean;
}

Example:

export default {
  future: {
    v8_middleware: true,
    v8_splitRouteModules: "enforce",
  },
};

Flags:

• unstable_optimizeDeps - Optimize dependency pre-bundling
• unstable_subResourceIntegrity - Generate SRI hashes for scripts
• unstable_trailingSlashAwareDataRequests - Handle trailing slashes in data requests
• unstable_previewServerPrerendering - Prerender with Vite preview server
• v8_middleware - Enable route middleware
• v8_splitRouteModules - Automatic route code splitting (true | "enforce")
• v8_viteEnvironmentApi - Use Vite Environment API

prerender

prerender · boolean | string[] | function | object

Defines which routes to prerender at build time as static HTML.

Types:

type PrerenderConfig = 
  | boolean  // true = all routes, false = none
  | string[] // Specific paths
  | ((args: { getStaticPaths: () => string[] }) => string[] | Promise<string[]>)
  | {
      paths: boolean | string[] | Function;
      unstable_concurrency?: number;
    };

Examples:

All Routes

export default {
  prerender: true,
};

presets

presets · Preset[]

Configuration presets for platform integrations.

interface Preset {
  name: string;
  reactRouterConfig?: (args: {
    reactRouterUserConfig: ReactRouterConfig;
  }) => ConfigPreset | Promise<ConfigPreset>;
  reactRouterConfigResolved?: (args: {
    reactRouterConfig: ResolvedReactRouterConfig;
  }) => void | Promise<void>;
}

Example:

import { cloudflarePreset } from "@react-router/cloudflare";

export default {
  presets: [cloudflarePreset()],
};

routeDiscovery

routeDiscovery · object

Controls lazy route discovery behavior.

type RouteDiscoveryConfig =
  | { mode: "lazy"; manifestPath?: string }
  | { mode: "initial" };

Default: { mode: "lazy", manifestPath: "/__manifest" } (when SSR enabled)

Examples:

Lazy (Default)

export default {
  routeDiscovery: {
    mode: "lazy",
    manifestPath: "/__manifest", // Custom path
  },
};

Lazy mode requires SSR. With ssr: false, mode is automatically "initial".

serverBuildFile

serverBuildFile · string · default: "index.js"

Filename for the server build output.

export default {
  serverBuildFile: "server.js",
};

Output: build/server/server.js

serverBundles

serverBundles · function

Split server code into multiple bundles based on route.

type ServerBundlesFunction = (args: {
  branch: BranchRoute[];
}) => string | Promise<string>;

interface BranchRoute {
  id: string;
  path?: string;
  file: string;
  index?: boolean;
}

Example:

export default {
  serverBundles({ branch }) {
    // Check if any route in branch starts with "routes/admin"
    const isAdminRoute = branch.some(
      (route) => route.id.startsWith("routes/admin")
    );
    
    const isApiRoute = branch.some(
      (route) => route.id.startsWith("routes/api")
    );
    
    if (isAdminRoute) return "admin";
    if (isApiRoute) return "api";
    return "main";
  },
};

Outputs:

build/server/
├── main/
│   └── index.js
├── admin/
│   └── index.js
└── api/
    └── index.js

serverModuleFormat

serverModuleFormat · 'esm' | 'cjs' · default: "esm"

Module format for server build output.

export default {
  serverModuleFormat: "cjs",
};

Most modern runtimes support ESM. Use CJS only if required by your deployment platform.

ssr

ssr · boolean · default: "true"

Enables server-side rendering. Set to false for SPA mode.

export default {
  ssr: false, // SPA mode
};

SPA Mode:

• Pre-renders / at build time
• Saves as index.html
• No server required
• All routes client-side only

allowedActionOrigins

allowedActionOrigins · string[]

Whitelist of allowed origins for form submissions. Supports glob patterns.

export default {
  allowedActionOrigins: [
    "example.com",
    "*.example.com",      // sub.example.com
    "**.example.com",     // sub.domain.example.com
  ],
};

Does not apply to resource routes (routes without UI components).

Runtime Override:

import type { ServerBuild } from "react-router";

async function getBuild(): Promise<ServerBuild> {
  const build = await import("./build/server/index.js");
  return {
    ...build,
    allowedActionOrigins: [
      process.env.ALLOWED_ORIGIN,
    ],
  };
}

Complete Example

import type { Config } from "@react-router/dev/config";

export default {
  appDirectory: "app",
  basename: "/",
  buildDirectory: "build",
  
  future: {
    v8_middleware: true,
    v8_splitRouteModules: "enforce",
  },
  
  async prerender({ getStaticPaths }) {
    const posts = await fetchPosts();
    return [
      "/",
      "/about",
      ...posts.map(p => `/blog/${p.slug}`),
      ...getStaticPaths(),
    ];
  },
  
  routeDiscovery: {
    mode: "lazy",
  },
  
  serverBundles({ branch }) {
    const isAdminRoute = branch.some(
      route => route.id.startsWith("routes/admin")
    );
    return isAdminRoute ? "admin" : "main";
  },
  
  serverModuleFormat: "esm",
  ssr: true,
  
  allowedActionOrigins: [
    "example.com",
    "*.example.com",
  ],
  
  async buildEnd({ buildManifest }) {
    console.log("Build completed!");
    // Custom post-build logic
  },
} satisfies Config;

Common Patterns

Multi-Region Deployment

export default {
  serverBundles({ branch }) {
    // Split by geographic region based on route prefix
    const path = branch[branch.length - 1]?.path || "";
    
    if (path.startsWith("/eu")) return "eu";
    if (path.startsWith("/asia")) return "asia";
    return "us";
  },
};

Development vs Production

const isDev = process.env.NODE_ENV === "development";

export default {
  buildDirectory: isDev ? "dev-build" : "build",
  
  future: {
    v8_middleware: !isDev, // Only in production
  },
  
  prerender: isDev ? false : ["/", "/about"],
};

Incremental Static Regeneration Pattern

export default {
  async prerender({ getStaticPaths }) {
    // Only prerender popular pages at build time
    const popular = await getPopularPages();
    return [
      "/",
      ...popular,
      // Other pages rendered on-demand
    ];
  },
};

Custom Build Artifacts

import { writeFile } from "fs/promises";

export default {
  async buildEnd({ buildManifest, reactRouterConfig }) {
    // Generate custom route manifest for analytics
    const routes = Object.keys(buildManifest.routes);
    await writeFile(
      "build/routes.json",
      JSON.stringify(routes, null, 2)
    );
    
    // Copy additional assets
    await cp(
      "locales",
      `${reactRouterConfig.buildDirectory}/client/locales`,
      { recursive: true }
    );
  },
};

TypeScript

Ensure proper type checking:

import type { Config } from "@react-router/dev/config";

export default {
  appDirectory: "app",
  ssr: true,
  // ...
} satisfies Config;

Validation

Config is validated at build time:

// ✅ Valid
export default {
  appDirectory: "app",
  ssr: true,
};

// ❌ Invalid - wrong type
export default {
  ssr: "yes", // Error: Expected boolean
};

// ❌ Invalid - incompatible options
export default {
  ssr: false,
  routeDiscovery: { mode: "lazy" }, // Error: lazy requires SSR
};

Related

• routes.ts
• reactRouter Plugin
• Deployment