README.md

React Router Adapter for Netlify

The React Router Adapter for Netlify allows you to deploy your React Router app to Netlify.

How to use

To deploy a React Router 7+ site to Netlify, install this package:

npm install @netlify/vite-plugin-react-router

Then include the Netlify plugin in your vite.config.ts:

import { reactRouter } from '@react-router/dev/vite'
import { defineConfig } from 'vite'
import tsconfigPaths from 'vite-tsconfig-paths'
import netlifyReactRouter from '@netlify/vite-plugin-react-router' // <- add this

export default defineConfig({
  plugins: [
    reactRouter(),
    tsconfigPaths(),
    netlifyReactRouter(), // <- add this
  ],
})

Note

This plugin automatically includes @netlify/vite-plugin, which provides full Netlify platform emulation directly in your local dev server.

Your app is ready to deploy to Netlify.

Deploying to Edge Functions

By default, this plugin deploys your React Router app to Netlify Functions (Node.js runtime). You can optionally deploy to Netlify Edge Functions (Deno runtime) instead.

First, toggle the edge option:

export default defineConfig({
  plugins: [
    reactRouter(),
    tsconfigPaths(),
    netlifyReactRouter({ edge: true }), // <- deploy to Edge Functions
  ],
})

Second, you must provide an app/entry.server.tsx (or .jsx) file. Create a file with the following content:

export { default } from 'virtual:netlify-server-entry'

Tip

If you prefer to avoid a @ts-ignore here, add this to vite-env.d.ts in your project root (or anywhere you prefer):

declare module 'virtual:netlify-server-entry' {
  import type { ServerEntryModule } from 'react-router'
  const entry: ServerEntryModule
  export default entry
}

Finally, if you have your own Netlify Functions (typically in netlify/functions) for which you've configured a path, you must exclude those paths to avoid conflicts with the generated React Router SSR handler:

export default defineConfig({
  plugins: [
    reactRouter(),
    tsconfigPaths(),
    netlifyReactRouter({
      edge: true,
      excludedPaths: ['/ping', '/api/*', '/webhooks/*'],
    }),
  ],
})

Moving back from Edge Functions to Functions

To switch from Edge Functions back to Functions, you must:

1. Remove the edge: true option from your vite.config.ts
2. Delete the app/entry.server.tsx file (React Router will use its default Node.js-compatible entry)

Edge runtime

Before deploying to Edge Functions, review the Netlify Edge Functions documentation for important details:

• Runtime environment - Understand the Deno runtime
• Supported Web APIs - Check which APIs are available
• Limitations - Be aware of resource limits and constraints

Load context

This plugin automatically includes all Netlify context fields on loader and action context.

If you're using TypeScript, AppLoadContext is automatically aware of these fields (via module augmentation).

For example:

import { useLoaderData } from 'react-router'
import type { Route } from './+types/example'

export async function loader({ context }: Route.LoaderArgs) {
  return {
    country: context.geo?.country?.name ?? 'an unknown country',
  }
}
export default function Example() {
  const { country } = useLoaderData<typeof loader>()
  return <div>You are visiting from {country}</div>
}

If you've opted in to the future.v8_middleware flag, you can still use the above access pattern for backwards compatibility, but loader and action context will now be an instance of the type-safe RouterContextProvider. Note that this requires requires v2.0.0+ of @netlify/vite-plugin-react-router.

For example:

import { netlifyRouterContext } from '@netlify/vite-plugin-react-router/serverless'
//                    NOTE: if setting `edge: true`, import from /edge ^ instead here
import { useLoaderData } from 'react-router'
import type { Route } from './+types/example'

export async function loader({ context }: Route.LoaderArgs) {
  return {
    country: context.get(netlifyRouterContext).geo?.country?.name ?? 'an unknown country',
  }
}
export default function Example() {
  const { country } = useLoaderData<typeof loader>()
  return <div>You are visiting from {country}</div>
}

Middleware context

React Router introduced a stable middleware feature in 7.9.0.

To use middleware, opt in to the feature via future.v8_middleware and follow the docs. Note that this requires requires v2.0.0+ of @netlify/vite-plugin-react-router.

To access the Netlify context specifically, you must import our RouterContext instance:

import { netlifyRouterContext } from '@netlify/vite-plugin-react-router/serverless'
//                    NOTE: if setting `edge: true`, import from /edge ^ instead here

import type { Route } from './+types/home'

const logMiddleware: Route.MiddlewareFunction = async ({ request, context }) => {
  const country = context.get(netlifyRouterContext).geo?.country?.name ?? 'unknown'
  console.log(`Handling ${request.method} request to ${request.url} from ${country}`)
}

export const middleware: Route.MiddlewareFunction[] = [logMiddleware]

export default function Home() {
  return <h1>Hello world</h1>
}