Re-introduce AppLoadContext as ServerBindings

[sergiodxa]

The new RouterContextProvider is great for middleware as you can safely read and write there

But AppLoadContext is great for cases where the HTTP server does need to inject things into RR apps, this is more common in CF apps where you receive D1, KV, R2, etc. bindings from AppLoadContext in your RR app, but it's also something apps may need to do with getLoadContext in other servers, for multiple reasons, specially when supporting older infrastructure.

This is why I thought that to keep both ideas, context can be repurposed for RouterContextProvider for middleware usage, and introduce a bindings argument (typed as ServerBindings interface) that can be used by server adapters

So in CF or another server you can do

let response = await handler(request, bindings)

Where bindings here is a ServerBinding object, and the server is in charge of typing it

declare module "react-router" {
  export interface ServerBindings {
    db: D1Database;
    kv: KVNamespace;
  }
}

But I would do a difference here, I would type loader, action and middleware args as Readonly<AppLoadContext>, and at runtime freeze the object too.

Then in one of those functions you will do:

export async function loader({ request, params, context, bindings }) {
  // bindings are ServerBindings
}

To ensure this bindings are considered something that RR apps only can read, but not change at runtime, if you want that use RouterContextProvider.

This is not only useful for CF apps that will be able to keep accessing CF bindings this server, but also other apps like Express that may need to support old code like maybe a data layer and inject it into RR

---

I know I can do this with RouterContextProvider by returning a Map in getLoadContext.

But AppLoadContext is just simpler to use, and gives a better DX for any code that doesn't need to be in a middleware.

As you don't need to import anything (e.g. import the context object), and you can just do context.something, and you know something will be there because your HTTP server is in charge of passing it

The RouterContextProvider should be limited to only middleware functions and not for the HTTP server usage instead.

[brophdawg11]

But AppLoadContext is just simpler to use, and gives a better DX for any code that doesn't need to be in a middleware.

I don't think the DX is much worse? It's 2 main changes for route files, assuming you stick your server context into a single object in the context provider:

• A new import for your context instance (import { serverContext } from "...";)
• context.db -> context.get(serverContext).db

The DX for appLoadContext was a tiny bit simpler at the cost of a worse typesafety and discoverability story.

The RouterContextProvider should be limited to only middleware functions and not for the HTTP server usage instead.

I personally think of the getLoadContext as sort of "just another middleware" that runs before the root route. In one of original implementations (before we tabled it for single fetch), opting into middleware replaced getLoadContext with an adapterMiddleware function to make that association clearer. But bubbling/handling errors from next becomes trickier at that level since you're outside of Remix.

Having separate context and bindings feels more confusing to me (plus more to maintain/document) when they are both "data injected earlier in the request flow".

[firxworx]

"at the cost of a worse typesafety and discoverability story"

You nailed it right there @brophdawg11!!

---

When I read that it was for "similarity to React.createContext" I couldn't understand why for a back-end / server-side functionality one would take inspiration from React and ultimately context of all things.

As I understand it, React Context benefits from Map-like approaches for performance -- zillions of components to render, lots of reading and writing going on, etc.

Meanwhile server-side context touched perhaps a handful of times during the servicing of a request by maybe some middleware and then finally in a loader or action.

Given that, I think the discoverability and type-safety wins out as well as the aforementioned developer familiarity , especially since back-end concepts and patterns are very stable and well-established; lots of solved problems unlike with front-end.

I think for remix/RR new devs should find that it builds on concepts from web development that they might already know.

Beyond being a curveball to backend devs, I think the pattern will confuse many front-end devs too. I don't think most could talk about how map and context are related as much as they can speak to how useState is really useReducer.

I argue that the average rank-and-file devs exposure to React context is using hooks like useAuth() or useTheme() with custom providers that encapsulate and abstract away the context API. These days they don't even see it or touch it a lot of the time.

The obscure take also means LLM's are unlikely to be very helpful to struggling devs.

---

I tried the new middleware in a playground app and vs. my previous project (first project ever in remix/RR) where I had a hono back-end and populated type-safe context (and also have full access to it via async local storage) it felt like a lot was missing.

A degree of type safety was gone, IntelliSense suggestions were gone, and I actually had more code in my actions and loaders vs. when I could e.g. be in an action and type context: { and have IntelliSense and auto complete for my db, i18n, etc.

Especially coming from hono where types just work and get passed down auto-magically and just work it felt less elegant.

RR has me editing .d.ts files and casting things... IDK. with hono I can change something in a middleware and poof there it is all the way over in my route with everything inferred or derived along the way.

---

Where does this lead ?

Discussions like this one, I get where Sergio is coming from (at least I think I do).

I think overall there's a risk of tending towards more complexity, and RR becoming more esoteric and obscure vs. easy and intuitive to pick up.

I'd benchmark against patterns with custom back-end and would challenge if the dev X is not as smooth than a pure RR solution for context + middleware then its a sign.

[rossipedia]

I have some strong opinions on this topic, I'll probably be adding more comments after this one, but my biggest disagreement is with this:

The DX for appLoadContext was a tiny bit simpler at the cost of a worse typesafety and discoverability story.

I don't think that AppLoadContext had either of those things. I'll even go further and state that RouterContextProvider has a demonstrably worse discoverability story, and since a picture is worth 1000 words, so to speak:

With RouterContextProvider, there is zero tooling assistance to help you understand what's available on context. You have to move away from the function you're writing to go find out what's there. You have to know where to import it from. You have to add more code to use things on context.

Granted, there is limited flexibility/composability with AppLoadContext, but I'd argue that in many cases you don't want that. Especially in an enterprise environment where you're providing a well-known set of primitives/tools to your engineers that they all must use.

However, I want to make clear that I don't think these things are mutually exclusive. I believe both approaches have their strengths and weaknesses, and more importantly serve different purposes.

AppLoadContext is critical in its current form for the apps I'm supporting. It's used to provide common tools that are guaranteed to be available in every loader/action across all of our applications.

Engineers can create a new route and immediately have access to the entire toolkit, no extra imports needed. This is not something I can provide with RouterContextProvider, and indeed if I have to tell my engineers that they need to add both a new import and an extra call to context.get(...) to retrieve the same toolkit that was previously available to them... that's gonna be a hard sell. And if I don't see the benefit, then I'm not going to be able to convince them otherwise, to be honest.

Regardless of whether or not there's a separate "bindings" or whatever you want to call it, the ability to provide a common set of... things... that are immediately available without any ceremony (import { blahContext } from 'somehwere'; and context.get(blahContext)) is, in my opinion, critical for a good DX. At least for the apps and devs I'm supporting.

Removing that ability for little to no benefit would leave a bad impression on both me and my engineers.

[purplesquirrels]

DX and type safety aside, the new context API changes mean we can no longer inject external dependencies into RR which is critical functionality that has been removed. It needs to be reinstated through the bindings proposal or some other form to avoid needlessly breaking or preventing the ability to update RR apps

[gustavopch]

As a workaround, you can bundle them together like this: remix-run/remix#9790 (reply in thread)

[purplesquirrels]

thanks @gustavopch, after a bit of faff I was able to kind of get it working based on the comment in that thread. I say kind of because while the context and middleware is working, it has broken HMR - I have to restart the server if I change any actions or loaders, and I get hydration errors in components when they are changed if I reload the page.

when editing a loader:
Error: [react-router:hmr] No module update found for route...

when editing a component:
Warning: Text content did not match. Server: "old text" Client: "hmr updated text"

I'll keep digging, but it seems like providing an equivalent API to what existed before would be much simpler.

[jarle]

Having to bundle the apps together is what threw me off. I compile the react-router app separately from the backend app, and now I have to tell vite to avoid pulling in adapter code into the react-router app, because otherwise the context keys don't match: https://github.com/jarle/remix-adonisjs/pull/98/files#diff-b4c0c4f06b4e3a616afc869e1a81d89ab96a3edf06e9255db8cdc104eca7c874R13-R16

The biggest downside compared to AppLoadContext is that the custom backend and react-router application has a shared compile-time dependency in the context key.

[zb140]

I'll keep digging, but it seems like providing an equivalent API to what existed before would be much simpler.

Did you ever find a solution you were happy with? I'm trying to solve the same problem right now, and I'm not willing to bundle the server and the app together -- the whole reason I'm running it this way in the first place is because I want them to be separate 😄.

[purplesquirrels]

I ended up getting the bundling of the server working, I don't think it's ideal but it's working ok for now - mainly the dev experience is a bit rough compared to the previous setup. Luckily my Express app was fairly simple. Would much prefer to have the apps separate though.

[Bricklou]

To add a little on top of everything that's been said, the current context API (using AsyncContext) seems to act like a dependency injection. Maybe it could be interesting to have some hybrid behaviour where:

• there are static injections (like explained in the first post: db, kv, r2)
• dynamic injections (the new context API)

Maybe having some way to provide both under the same context object? For example:

import { userContext } from '~/contexts/user'

const db = context.db // typed as `D1Database` from the type expansion
const kv = context.kv // typed as `KVNamespace` from the type expansion
const user = context.inject(userContext) // will inject the type `UserCtx | undefined` from the context object like it does with the current API

This way, we can keep the good part from both world without having to use some extract variable from the args.

And under the hook, it still could be a Map, it's just that there are some typings magic happening to allow the discovery.

Edit:
Another suggestion that would be interesting is to allow developers to use their own implementation for the context object. This way, they can implement it the way they want.

[firxworx]

FYI adding react-router to a hono app can be straightforward:

// createRequestHandler is imported from react-router
// this example assumes vite is bundler

// @ts-ignore -- types of virtual module will not resolve type until first build
const build = await import('virtual:react-router/server-build')
const requestHandler = createRequestHandler(build, import.meta.env.MODE)

for the hono app after adding any middleware and any non-react-router API routes you can hand off the remaining responsibility to react-router and pass along the context:

  .all('*', async (ctx) => {
    return await requestHandler(ctx.req.raw, {
      appVersion: import.meta.env.PROD ? build.assets.version : 'dev',
      flags: ctx.get('flags'),
      db: ctx.get('db'),
      locale: ctx.get('locale'),
      i18next: ctx.get('i18next'),
      auth: ctx.get('auth'),
      user: ctx.get('user'),
      session: ctx.get('session'),
      cloudflare: {
        env: ctx.env,
        ctx: Object.assign(ctx.executionCtx, { props: undefined }), // typescript wants to see `props`
      },
    })
  })

(this example uses the previous context but its very similar for the new unstable context; not shown is declaring types so typescript knows what is available on react-router context).

[benfosterlitmos]

I looked into AsyncLocalStorage as an alternative but it has the same problem where you need a reference to the AsyncLocalStorage object in order to get the store. I haven't used Hono before, but I think the key there is that Hono is bundled? So your RR and Hono code is bundled into the same app? This is basically what others have suggested by bundling Express + RR apps together. I did end up getting this working but it does make it a bit more complicated because you can't just serve a RR app on an Express route without either changing your entire setup to use Vite or introducing the bundling to the entire application if it wasn't bundled before.

[firxworx]

@benfosterlitmos yessir in this case hono is indeed bundled as one thing: the server-side of the application is driven by hono.

remix used express as the default backend so it was already there anyway even if hidden from you.

This example is probably a bit more relevant to Bricklou because they're clearly using Cloudflare which is big on the @cloudflare/vite-plugin these days. Th vite.config.ts for this is actually every simple, here's an example:

import { defineConfig } from 'vite'
import tsconfigPaths from 'vite-tsconfig-paths'
import { cloudflare } from '@cloudflare/vite-plugin'
import { reactRouter } from '@react-router/dev/vite'
import tailwindcss from '@tailwindcss/vite'

// ... inside the export default defineConfig ...

  plugins: [
    cloudflare({
      viteEnvironment: { name: 'ssr' },
      inspectorPort: 9229,
      persistState: { path: '../../.wrangler/state' },
    }),
    tailwindcss(),
    reactRouter(),
    tsconfigPaths(),
  ],

The Cloudflare plugin requires the viteEnvironmentApi. Here's example react-router.config.ts:

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

export default {
  ssr: true,
  future: {
    unstable_viteEnvironmentApi: true,
  },
} satisfies Config

It all looks so simple now but I spent some evenings bashing keyboard through the different options for hono, react-router, bundling, vite configs, etc. before I landed on the simplified approach!

Glad you got your way with express working :)

[firxworx]

For any readers, for clarity, the one missing piece not mentioned is wrangler.jsonc (cloudflare config) that points to the entry file (hono in this case):

  "main": "./workers/app.ts",

This config is different depending on if you are using the cloudflare vite plugin or not.

[Maxservais]

I'm using React Router v7 with Hono for SSR on Cloudflare and getting this error when trying to access context.cloudflare in loaders:

export function loader({ context }: Route.LoaderArgs) {
  // Error: 'context.cloudflare' is of type 'unknown'
  return { message: context.cloudflare.env.VALUE_FROM_CLOUDFLARE };
} 

export default function Home({ loaderData }: Route.ComponentProps) {
  return (
    <div>
      <p>{loaderData.message}</p>
    </div>
  );
}

I'm working with the example at https://github.com/kristianfreeman/react-router-hono-vite-cf-example

I've read through the proposed solutions in this discussion (ServerBindings, Hono's context storage, helper functions, etc.) but I would really appreciate if someone could share their implementation as I struggle a bit here.

Thanks in advance!

[brophdawg11]

Thank you everyone for the feedback!

It sounds like the main concerns with RouterContextProvider are the following - loosely ordered in descending order of my own opinions about the associated developer pain (earlier = more annoying):

1. Lack of recognition between the use cases of purely global data handed off from the server (which is always populated) versus route-specific middleware data (which is conditionally populated based on the matched route middlewares)
2. Less discoverability via autocomplete when typing context.
   • I think this is largely alleviated by keeping the # of contexts low and storing them in a single contexts.ts file
   • I think the commonly used ones would become muscle memory pretty quickly
3. You need to bundle server/app code to maintain the same context instances
   • As pointed out this would also be an issue with AsyncLocalStorage and in many apps it's not an issue to bundle
4. Extra import required in route files to use with context.get/.set
   • I don't think this is a big deal and personally like the discoverability of "where did this value come from" compared to just a magical value on context that you have no direct indication of how it got there when reading the source code of your route file.
   • I have a similar concern with AsyncLocalStorage use cases too

That said, I do think bullet (1) is a valid and nuanced difference in that some data is truly global/always available on every request, has to be done at the HTTP server level (instead of the root route) and having it hanging directly off context is pretty handy for those cases (see bullet (2)).

I do think that context.set(serverContext, { ...currentAppLoadContext }) and context.get(serverContext) is a fine solution for these global aspects (1 additional import and a few extra characters in a loader), but it's also a bit of a pain to migrate to.

I also think a lot of use cases of getLoadContext today can and should move to root middleware where it'll still always be there but isn't coupled to the HTTP server - it just lived in getLoadContext because we lacked a better alternative until middleware came along.

---

Here's what I'm thinking as a bit of a compromise:

We alter getLoadContext so that you return us a RouterContextProvider, instead of the InitialContext map we currently use to construct the RouterContextProvider instance internally. This puts you in change of construction of the instance, instead of us. This mostly removes the InitialContext idea entirely so one less type to be aware of, and it also aligns a bit better with AppLoadContext where you created the object instance and handed it to us.

app.use(
  createRequestHandler({
    build,
    getLoadContext() {
      let context = new unstable_RouterContextProvider();
      context.set(someContext, someValue);
      return context;
    },
  })
);

Otherwise - everything else remains the same - the normal path is still to populate via context.set and read via context.get.

However, this change opens up the ability for you to use existing features of JS/TS to re-implement the AppLoadContext-DX - totally outside of React Router. Because RouterContextProvider is just a class and it's JS you can just stick new properties directly on the instance, and you can use TS augmentation to make them typesafe:

declare module "react-router" {
  interface unstable_RouterContextProvider {
    VALUE_FROM_EXPRESS: string; // 👈 Totally valid user-land TS
  }
}

app.use(
  createRequestHandler({
    build,
    getLoadContext() {
      let context = new unstable_RouterContextProvider();
      context.VALUE_FROM_EXPRESS = "Hello from Express";  // 👈 Totally valid user-land JS
      return context;
    },
  })
);

Then in your actions/loaders, you get these alongside get/set:

I don't think we'd necessarily recommend/document this pattern, but we also can't stop you since it's entirely outside of our area of concern. You create/own the context and we just plumb it around for you. I personally think this would make for a much better migration story (and maybe we could document it as such), with the end recommendation still being to drop the augmentation in the long run. We do enforce it being that shape because of the enhanced type safety and because we want some consistency across apps so that middlewares can be easily shared/published/composed together across apps without conflicts.

What do you think? Would that work for the use cases you all have outlined here? I'm going to review this with the other SC members soon too and get their thoughts.

I've tested this in a simple app locally and it works great - the one outstanding thing in my head is that we probably need to differentiate the thing you augment for the server side from the client side so Route.ClientLoaderArgs["context"] doesn't reflect the server augmented types, but I think that should be doable.

[sergiodxa]

What do you think of typing context in LoaderArgs and ActionArgs as read-only? It can be ReadOnly<RouterContextProvider>, this can help ensure that inside RR the only way to mutate the context is using context.set and not context.key = value

[rossipedia]

💯

This pattern is essentially what we're doing today, except the "enhancement" of unstable_RouterContextProvider happens in loader and action wrappers, which unfortunately means those extra properties aren't available in entry.server.tsx, so this solution would be super handy to make all those properties available consistently.

[brophdawg11]

This is implemented in #14097 and an alpha release should be out shortly if folks want to test this out

[brookslybrand]

Just tried it on shop.remix.run. Migration was super easy, took like 10 minutes and doesn't seem like it's broken (on preview deploy)

This is a very good approach for the migration path. Remix store isn't even that complicated, but it relies on app load context a lot, and the migration would have been pretty annoying just to get middleware

[jrestall]

This is great, saved us having to change 500+ code files and update as many tests for one of our apps. Works great, looking forward to release.

[brophdawg11]

I'm going to close this out since it was handled in an alternate way (see #13331 (comment)).