React Router on Easel

Easel deploys React Router 7 and 8 applications in Framework Mode. Add one deployment preset, and Easel serves browser assets and prerendered pages from the CDN and runs server rendering, loaders, actions, and resource routes in Functions. For how the platform fits together, see How Easel works.

At a glance

Deploy a React Router application

Install the deployment preset:

npm install -D @vercel/react-router

Add it to react-router.config.ts:

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

export default {
  presets: [vercelPreset()],
} satisfies Config;

The preset makes the build write the server entry Easel deploys. Then create a project and connect the Git repository, or deploy with the CLI:

easel deploy

Easel detects the project and runs react-router build. You can override the install command, build command, root directory, and Node.js version in build configuration.

React Router 7 and 8

React Router 8 is a non-breaking upgrade from 7, but it requires Node.js 22.22.0 or newer, React 19.2.7 or newer, Vite 7 or newer, and an ESM project. It also turns the future.v8_* behaviors on by default. Existing React Router 7 applications deploy without upgrading. Set the project's Node.js version to one that meets React Router 8's baseline before you upgrade.

To upgrade, move to the latest React Router 7 release, enable the future.v8_* flags and fix what they surface, then upgrade the React Router packages together, remove the flags, and test in a preview deployment.

What Easel deploys

The preset exposes the route structure, so server bundles can be split by route instead of shipping the whole server application as one Function.

Supported features

Loaders and actions

Server rendering is on by default in Framework Mode. A loader runs on the server and passes data to the component through generated route types:

import type { Route } from "./+types/product";

export async function loader({ params }: Route.LoaderArgs) {
  const product = await getProduct(params.productId);

  if (!product) {
    throw new Response("Not found", { status: 404 });
  }

  return { product };
}

export default function Product({ loaderData }: Route.ComponentProps) {
  return <h1>{loaderData.product.name}</h1>;
}

A document request invokes the application Function and streams the rendered response. After hydration, client navigations fetch loader data from the same Function without rerendering the document. Actions handle form submissions the same way, and redirects, cookies, and error boundaries follow the framework's normal response flow.

Streaming

A loader can return unresolved promises, and React Router streams the document before they settle:

import { Await } from "react-router";
import { Suspense } from "react";
import type { Route } from "./+types/dashboard";

export async function loader() {
  return {
    account: await getAccount(),
    activity: getRecentActivity(),
  };
}

export default function Dashboard({ loaderData }: Route.ComponentProps) {
  return (
    <Suspense fallback={<p>Loading activity…</p>}>
      <Await resolve={loaderData.activity}>
        {(activity) => <ActivityList activity={activity} />}
      </Await>
    </Suspense>
  );
}

Easel forwards chunks as React Router produces them. The Function stays active until the stream closes.

Middleware

Server middleware runs inside the application Function before and after the matched route's handlers. Use it for authentication, request context, and response headers. It's separate from the Firewall, which runs before a Function is invoked.

import { createContext, redirect } from "react-router";
import type { Route } from "./+types/dashboard";

export const userContext = createContext<User>();

const requireUser: Route.MiddlewareFunction = async (
  { request, context },
  next,
) => {
  const user = await authenticateRequest(request);

  if (!user) {
    throw redirect("/login");
  }

  context.set(userContext, user);
  return next();
};

export const middleware: Route.MiddlewareFunction[] = [requireUser];

export async function loader({ context }: Route.LoaderArgs) {
  return { user: context.get(userContext) };
}

Pass per-request data through context, not module-level variables. One Function instance handles many requests.

Middleware is on by default in React Router 8. React Router 7 releases that support it need the future flag:

export default {
  presets: [vercelPreset()],
  future: {
    v8_middleware: true,
  },
} satisfies Config;

Response caching

Routes set CDN behavior with standard Cache-Control headers from a headers export:

export function headers() {
  return {
    "Cache-Control": "public, s-maxage=60, stale-while-revalidate=300",
  };
}

Use private, no-store for responses that depend on the user or session. See CDN caching for how Easel caches and keys responses.

Static prerendering

List routes to generate during the build:

export default {
  presets: [vercelPreset()],
  async prerender() {
    return ["/", "/about", "/pricing"];
  },
} satisfies Config;

Easel deploys the generated HTML to the CDN. Requests for prerendered routes don't invoke a Function.

SPA mode

Set ssr: false to deploy a client-rendered application:

export default {
  ssr: false,
  presets: [vercelPreset()],
} satisfies Config;

Easel serves the build from the CDN and routes application paths to the SPA entry document. Server loaders and actions aren't deployed. clientLoader and clientAction still work. If the application uses React Router only in Data Mode or Declarative Mode, follow the Vite guide instead.

Sessions and environment variables

Cookie sessions from createCookieSessionStorage work through standard Set-Cookie headers and need no server storage. Use a database for session state that's too large for a cookie or must be revoked centrally.

Server code reads variables from process.env. Don't pass process.env to the browser. Return an explicit allowlist of public values from the root loader instead. See environment variables for scopes and how changes apply.

Project configuration

In a monorepo, set the root directory to the folder containing the application's package.json, react-router.config.ts, Vite config, and routes. See monorepos.

Keep using react-router dev locally, and use a preview deployment to check the production server bundle, caching, and streaming.

Known limitations

• WebSockets. Functions can't hold long-lived WebSocket connections. See Functions runtime.
• Custom Node.js servers. Easel deploys the Web API request handler the preset generates. An application that needs to own a persistent HTTP server, raw TCP sockets, or process-level connection handling needs a separate service.

Troubleshooting

The build fails after upgrading to React Router 8

Check the Node.js, React, and Vite versions against React Router 8's baseline, and confirm the project is ESM. Then remove obsolete future.v8_* flags and check that @vercel/react-router and your Vite plugins support v8.

Middleware doesn't run in React Router 7

Check that the installed release supports middleware and that future.v8_middleware is on. A client navigation to a route with no server loader or action doesn't reach the server, so server middleware doesn't run.

A loader runs locally but not in production

Check that ssr: false isn't set. SPA mode doesn't deploy server loaders or actions.

Deep links return 404 in SPA mode

Build with React Router's SPA mode and the preset, not as a plain Vite static build. The framework output includes the fallback route Easel needs.

Compatibility policy

Easel tests this guide against the version in At a glance. Test new React Router releases in a preview deployment first. See the compatibility policy.

Next steps