React Router 7+ Vite plugin for Netlify
npm install @netlify/vite-plugin-react-routerThe React Router Adapter for Netlify allows you to deploy your React Router app to Netlify.
To deploy a React Router 7+ site to Netlify, install this package:
``sh`
npm install @netlify/vite-plugin-react-router
It's also recommended (but not required) to use the
Netlify Vite plugin, which provides full Netlify platform
emulation directly in your local dev server:
`sh`
npm install --save-dev @netlify/vite-plugin
and include the Netlify plugin in your vite.config.ts:
`typescript
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
import netlify from '@netlify/vite-plugin' // <- add this (optional)
export default defineConfig({
plugins: [
reactRouter(),
tsconfigPaths(),
netlifyReactRouter(), // <- add this
netlify(), // <- add this (optional)
],
})
`
Your app is ready to deploy to Netlify.
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:
`typescript`
export default defineConfig({
plugins: [
reactRouter(),
tsconfigPaths(),
netlifyReactRouter({ edge: true }), // <- deploy to Edge Functions
netlify(),
],
})
Second, you must provide an app/entry.server.tsx (or .jsx) file. Create a file with the following content:
`tsx`
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):`
>
> typescript`
> 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:
`typescript`
export default defineConfig({
plugins: [
reactRouter(),
tsconfigPaths(),
netlifyReactRouter({
edge: true,
excludedPaths: ['/ping', '/api/', '/webhooks/'],
}),
netlify(),
],
})
#### 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.tsapp/entry.server.tsx
2. Delete the 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
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:
`tsx
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
return You are visiting from {country}
}
`
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:
`tsxedge: true
import { netlifyRouterContext } from '@netlify/vite-plugin-react-router/serverless'
// NOTE: if setting , 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
return You are visiting from {country}
}
`
> [!IMPORTANT]
>
> Note that in local development, netlifyRouterContext requires Netlify platform emulation, which is provided@netlify/vite-plugin
> seamlessly by (or Netlify CLI - up to
> you).
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:
`tsxedge: true
import { netlifyRouterContext } from '@netlify/vite-plugin-react-router/serverless'
// NOTE: if setting , 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
> [!IMPORTANT]
>
> Note that in local development,
netlifyRouterContext requires Netlify platform emulation, which is provided
> seamlessly by @netlify/vite-plugin` (or Netlify CLI - up to