How to provide a populated RouteContextProvider from BYO server?

[Nick-Minutello]

We started with remix and BYO server (koa).

The server code populates the AppLoadContext with various server side resources (client connections and the like) that are expensive to create on startup.

Upgrading from RR7 to RR8, we are running into issues.

All works fine as an RR7 AppLoadContext, but the problem with the RouterContextProvider is the duplicate module loading for the keys (RouterContext). The RouterContextProvider is populated with key loaded by the server module but routes try to get() from RouterContextProvider with key loaded by the app module loader. It always encounters the error “No vale found for context”

How is this meant to work? How are we supposed to pass context from the server to the app?

[dgesteves]

The keys are matched by object identity. createContext() just returns a new { defaultValue } object, and RouterContextProvider stores values in a Map keyed by that object (source, 8.4.0). When Koa imports app/context.ts itself and the routes use the copy Vite bundled into build/server/index.js, there are two different key objects, so get() throws. AppLoadContext used plain string properties, which is why v7 never ran into this.

The fix is to move the code that builds the context into the Vite build, so only one copy of the keys exists. The official node-custom-server template does exactly this. To keep your expensive resources created once at startup, export a factory from the build and pass them in:

// server/app.ts (compiled into build/server/index.js)
import { RouterContextProvider } from "react-router";
import { resourcesContext, type Resources } from "../app/context";
import { createKoaHandler } from "./koa-adapter"; // whatever wraps createRequestHandler today

export function createReactRouterMiddleware(resources: Resources) {
  return createKoaHandler({
    build: () => import("virtual:react-router/server-build"),
    getLoadContext() {
      const context = new RouterContextProvider();
      context.set(resourcesContext, resources);
      return context;
    },
  });
}

// vite.config.ts
export default defineConfig({
  environments: {
    ssr: { build: { rollupOptions: { input: "./server/app.ts" } } },
  },
  plugins: [reactRouter()],
});

// server.js (your Koa entry, not bundled)
const resources = await createResources(); // once, at startup
const app = new Koa();

if (process.env.NODE_ENV === "development") {
  const vite = await (await import("vite")).createServer({
    server: { middlewareMode: true },
    appType: "custom",
  });
  // mount vite.middlewares (connect-style) here
  app.use(async (ctx, next) => {
    const { createReactRouterMiddleware } = await vite.ssrLoadModule("./server/app.ts");
    return createReactRouterMiddleware(resources)(ctx, next);
  });
} else {
  const { createReactRouterMiddleware } = await import("./build/server/index.js");
  app.use(createReactRouterMiddleware(resources));
}

In dev, ssrLoadModule("./server/app.ts") loads the server code into the same Vite module graph as the routes, so there's one copy there as well.

If you'd rather keep the server outside the build, add export { resourcesContext } from "./context"; to app/entry.server.tsx. The server build exposes that module as build.entry.module (source), so read the key from there instead of importing it. In dev, read it from ssrLoadModule("virtual:react-router/server-build").

Two things that won't work on their own:

• Putting the keys in a workspace package: Vite inlines symlinked packages into the SSR build, so you end up with two copies again. Adding the package to ssr.external fixes it.
• Returning a plain object: v8 rejects it with "Invalid context value provided to handleRequest" (changelog). Object.assign(new RouterContextProvider(), oldContext) still works in 8.4.0, but the v7 docs offered it only as a migration step, and it's no longer in the v8 docs.

Tested with react-router, @react-router/dev and @react-router/node 8.4.0, Vite 8.3.4, Koa 3.2.1 and Node 24.18, against the react-router build output and in Vite middleware mode.

[mgkvibez]

Building on the object-identity answer above — the practical fix is to make both sides of your server share one module registry, because the duplication isn't in the context API, it's in how the modules get loaded.

What's happening: your koa bootstrap loads the module that calls RouterContext() with one loader (Node's require/import), while the app runs through Vite's SSR pipeline. Same file, two module instances, two distinct context objects — so get() on the app side looks up a key that isn't in the Map.

Ways out, pick one:

1. Load your context-keys module through the same pipeline as the app: use the Vite dev server's ssrLoadModule (or the build-time SSR output) for the server-side import instead of a separate tsx/esm loader. One module graph, one object identity.

2. If the server must keep its own bootstrap loader, externalize the shared contexts into a package that both sides import as a proper dependency (not a path alias that resolves differently per side). Package resolution gives you a single instance; ad-hoc aliases give you the mismatch you're seeing.

3. The cheap escape hatch: since the values only need to flow server → app, sidestep context identity entirely for that payload — put the expensive resources on a global or a server-singleton exported from the same module the request handler uses, and read that in loaders.

Option 1 is the cleanest — it also fixes any future double-instantiation bugs of the same kind (singletons, class instances, anything identity-sensitive).