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

[brophdawg11]

Why not? You still have getLoadContext in which you return an initial Map of contexts/values.

[purplesquirrels]

Because getLoadContext now requires returning a map where the key is a context created by unstable_createContext so the context needs to be imported on both sides. This isn't possible unless both the RR app and the external environment (eg Express server) are bundled together, which isn't necessarily a viable solution.

[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.

[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!