🗺️ Server Context

[ryanflorence]

Server context allows you to create a value in one place and share it across the rest of the route hierarchy below the context: data, abstractions, dependency injection, etc.

It should replace the need for getLoadContext in adapters making it possible to share context abstractions between apps using different server adapters. It also enables context at the route level instead of the app level.

Proposal

Future Flag

This feature depends on the single fetch and middleware flags, and will likely just be implemented along with middleware as the same flag.

{
  future: {
    unstable_singleFetch: true;
    unstable_middleware: true;
  }
}

Signature

async function myContextFunction({ request, match, context }) {
  return { some: "thing" };
}

type ServerContext<Context> = {
  request: Request
  params: Params
  context: Context
}: Promise<Context> | Context

Usage in Routes

Server Context is defined as a route module export. The defining route and all routes below the context will have access to the contexts created, accessible by the key used in the route definition. Multiple contexts can be created in a single context route.

export const context = {
  db: getMyDataStorageContext,
  payments: getMyPaymentsContext,
};

Context can be accessed in various places in your app:

// in loaders
export function loader({ context }) {
  let { db, payments } = getContext();
  // ...
}

// in actions
export function action({ context }) {
  let { db, payments } = getContext();
  // ...
}

// Middleware beneath the context
function someMiddleware({ request, params, context }) {
  let { db, payments } = context;
  // ...
}

// Other contexts beneath the context
function someContext({ request, params, context }) {
  let { db, payments } = context;
  // ...
}

Example

Some databases allow you to create a connection that is scoped to an individual user. This allows you to create a connection to the database once per request and share it across the entire app.

Context Definition

export function getDbContext({ request: Request }) {
  let userId = myGetUserIdFromRequest(request);
  let db = myCreateDbConnection(userId);
  return db;
}

Route Configuration

export const context = {
  db: getDbContext,
};

// context runs before middleware for a route
export const middleware = [queryTimingHeaders];

Middleware Access

function queryTimingHeaders({ request, context, next }: Middleware) {
  myCaptureTimingsFor(request, context.db);
  let response = await next();
  let timings = await getTimingsFromDb(request);
  response.headers.append("Server-Timings", timings);
}

Loader/Action Access

export async function loader({ params, context }) {
  return context.db.getThing(params.someId);
}

export async function action({ params, context }) {
  const formData = await request.formData();
  return context.db.writeThing(formData.get("title"));
}

[itsMapleLeaf]

There was a proposal a while ago that I liked which worked similarly to react context. I like this for its inherent type safety:

// database-context.ts
export const databaseContext = createServerContext<Database>()

export async function setDatabaseContext({ request, context, next }: MiddlewareArgs) {
  let userId = myGetUserIdFromRequest(request)
  let db = myCreateDbConnection(userId)
  databaseContext.set(context, db)
  return next()
}

// timing-headers.ts
import { databaseContext } from './database-context.ts'

export async function queryTimingHeaders({ request, context, next }: MiddlewareArgs) {
  const db = databaseContext.get(context) // throws if not set, maybe add a `getOptional` function for the alternate case?
  myCaptureTimingsFor(request, db);
  let response = await next();
  let timings = await getTimingsFromDb(request);
  response.headers.append("Server-Timings", timings);
}

// root.tsx
export const middleware = [setDatabaseContext, queryTimingHeaders]

[ryanflorence]

Oh dang I forgot about that!

With our RSC work the context will be inferred without needing that extra createServerContext(), so I'm thinking we can just stick with generics in the MiddlewareArgs<Contetext> and LoaderArgs<Context> for now.

But this is back on my radar, thank you.

[afoures]

Nice, how would the context type works? Especially when multiple routes would define some context, will we have to merge the types ourselves?

[ryanflorence]

It'll look something like props to components:

export async function loader({ context }: LoaderArgs<{ blog: Blog, db: Db }>) {
  // ...
}

We might use the second argument too:

export async function loader(
  { request }: LoaderArgs,
  context: { blog: Blog; db: Db }
) {
  // ...
}

[sergiodxa]

So we have to track those type?

[ryanflorence]

Typescript gives us no way to type a module. We've got other plans for this stuff in the future where it's all inferred and glorious, but if you're using file system routing there's no way to do that unless you know something we don't.

[ryanflorence]

We could also revisit the context.get(SomeContext) API, which would require an extra module and some mostly meaningless runtime code instead of type annotations: #7644 (comment)

[KevinMind]

Codegen could theoretically help here? With file based routing, I can traverse the pages folder and collect all the exported context properties, rolling them into a union as deep as the route is. Then each route can import the generated type like graphql codegen types. This would require a lot of static code generation though, probably not the best DX.

Would probably make sense to put off in some parallel file system like sorbet does for ruby code.

@ryanflorence any links to We've got other plans for this stuff in the future where it's all inferred and glorious discussions around this?

[pullmann4rent]

Do I get scaling problems when I use serverside context ?

[cythrawll]

One of the things my team has been using getLoadContext in our express adapter is passing data from our express middlewares into the remix app. This proposal doesn't seem to cover that use case where we have data from our adapter that doesn't fit in request/response objects that we'd like to pass into the app. Will this new approach mean deprecation of getLoadContext?

[itsMapleLeaf]

What express-specific data do you have that can't be derived on its own within context functions? (actual question, I'm curious)

[cythrawll]

Corporate provided express middleware that does complex parsing and verification of things in the request headers. The remix app needs to know the result of that process.

[ryanflorence]

yes, adapters will still be able to pass values into the remix app. Didn't mean to imply that getLoadContext would be removed.

[sergiodxa]

From what I understand, Server Context is used to define values that other parts of the request flow can access and is needed because middlewares can't do that?

Wouldn't it be better to merge this with middlewares? So you can define this getDbContext as a middleware in root and then every other middleware, loader or action can access the DB connection somehow?

I think that's how middlewares typically work in other frameworks like Express or Hono, e.g. being similar to Hono:

export function middleware({ request, params, context, next }) {
  let userId = myGetUserIdFromRequest(request)
  ctx.set("db", myCreateDbConnection(userId))
  await next()
}

export function loader({ context }) {
  let db = context.get("db")
  // use db here
}

This also enables a pattern I like in Hono where you can use a Symbol as context key and then hide (and type) accessing the context behind a function

// app/services/db.server.ts
const DB = Symbol()

export function middleware({ request, params, context, next }: MiddlewareFunctionArgs) {
  let userId = myGetUserIdFromRequest(request)
  ctx.set(DB, myCreateDbConnection(userId))
  await next()
}

export function getDB(context: ServerContext) {
  let db = ctx.get(DB)
  if (db instanceof Database) return db
  throw new Error("Missing DB in context")
}

// in some route
export function loader({ context }: LoaderFunctionArgs) {
  let db = getDB(context)
  // use db here which is typed as Database instance
}

[itsMapleLeaf]

I meant to add the generic to begin with; updated!

[ryanflorence]

The reason to split them is to keep responses as fast as possible.

• Middleware must be called sequentially
• Context can be called in parallel

If we mixed the two concepts together, then getting multiple context values into the app would block each other, artificially slowing down responses.

With file-based routing it's definitely more cumbersome this way, but in the future we have a runtime route config that makes it very natural to place middleware/context in whichever order is needed and all types are inferred.

[ryanflorence]

Though, looking at that old proposal for context and @itsMapleLeaf's sample code, it does look pretty appealing to set contexts in middleware that way.

I'm still worried about artificial request chains though. I want an API that makes it really hard to introduce them.

function someMiddleware() {
  DB.set(context, await connectDB());
  SDK.set(context, await someSDK());
  // oops
}

[sergiodxa]

• Middleware must be called sequentially
• Context can be called in parallel

This makes sense to me, and I agree that it will be hard to avoid introducing artificial waterfalls in middlewares, I saw this for Hono middlewares too, if one is async it just blocks every other middleware.

[sergiodxa]

I'm starting to play with middlewares and Server Context ideas to plan a new version of Remix Auth, and so far I find myself needing a way to set context in the middleware but not so much the Server Context proposal.

I could use Server Context to parse the session once, but I was thinking on a middleware to authenticate the user and I need somehow a way to update the server context so I can pass the user to the loaders/actions.

Without that I can check the user is authenticated but then I need to do it again in the loader/action, or I need to put the user on context first and only authenticate in the middleware. But that will split in two functions what could and should be one functions, so instead of this

export const context = { user: authenticator.getUser }
export const middlewares = [authenticator.requireUser({ failureRedirect: "/login" })]

I could do just this:

export const middlewares = [authenticator.authenticate({ failureRedirect: "/login" })]

And let authenticator.authenticate read the user and authenticate it (redirect to /login if user is null), and the loader can still access the user.

[owlyowl]

I know Shopify have a code freeze in the works but I was wondering if there was an eta on this kind of functionality. At present we're building out on the Remix App Template and AWS with a DynamoDB Session provider.

As part the server loaders we perform API request signing via a Cognito lookup to hit our private APIs.

Because there is no concept of server context we can use a bit of caching to store credentials per session but having a shared context would be incredibly useful rather than looking up/caching per loader.

We had a look at getLoadContext but it doesn't seem suitable for this kind of thing.

Unless there's something else in our understanding Remix we're missing at present, the paralellization of loader execution means currently it's not possible to share session/context across loaders and rather look them up each time?

[sergiodxa]

Thinking about the usage, instead of this

export const context = {
  db: getMyDataStorageContext,
  payments: getMyPaymentsContext,
};

Would it be possible to do without keys?

export const context = [getMyDataStorageContext, getMyPaymentsContext]

They can still run in parallel (like if you did Promise.all), I'm thinking for a library that wants to inject something into context, e.g. for Remix Auth, with the current usage proposed I would need to ask the user always for the same key, e.g. to make the session available always use:

export const context = { session: authenticator.session }

If they used another key any middleware depending on that code will not work anymore.

Instead if it was an array that received a mutable context object, I could do something like this:

const symbol = Symbol()

async function session(request, context) {
  let session = await sessionStorage.getSession(request.headers.get("cookie"))
  context.set(symbol, session)
}

export const context = [session]

function getSession(context) {
  return context.get(symbol) as Session | null
}

function requireUser(request, context) {
  let session = getSession(context)
  if (!session) throw redirect("/login")
}

export const middleware = [requireUser]

By doing this I can ensure my middleware has access to the correct Symbol and it can retrieve the context value I need as long as the context is defined, I think the context object could be a Map instance.

let context = new Map<Symbol, unknown>()

[niconiahi]

would it be too crazy to allow the user, on a per route fashion, how to run the context + middleware + loader/actions?

I'm just thinking of something like

export const run = [middleware, context, action, loader]

in which the first element runs first, the second, second, so on

allowing a really powerful pattern in my opinion where by simply moving the elements of the array from one place to the other, you are setting the rendering you want

[reconbot]

I think a major improvement this brings is that is not easy to include typescript into getLoadContext. Right now anything in your custom server skips the build chain and you have to figure it out yourself.

[reconbot]

Additionally it makes it much easier to have dependency injection. Most apps of any size I've worked on end up with an application context that has global concerns (eg; what email server or database are we talking to?) and a request context that has request scoped concerns (auth and session info).

I like this route based approach as you can inject only relevant context but in practice just having the two entry points (app and request) covers 99% of use cases I've worked with. And it makes it easy to pass the context to functions that do the backend business logic, which keeps them testable and side effect free.

[panzerdp]

It would be really great to have this RFC implemented in Remix. The lack of middleware/server-context/route-context in Remix makes it so hard to handle cross cutting concerns (like auth) in a single place.

The existing getLoadContext() is at the too low level, and it's useful mostly to get data from the adapter.

[cliffordfajardo]

You could put your auth code in root.tsx file. For example, in one of the app's that I have, I put the authentication check at the top of root.tsx's loader.

// File: root.tsx

export const loader: LoaderFunction = async ({ request }) => {
  const pathname = new URL(request.url).pathname;
  /* SSO */
  const user = await authenticator.isAuthenticated(request);
  if (!user && pathname !== "/login") {
    throw redirect(`/login?redirect=${pathname}`);
  }
  /* End SSO */
  return json({
    user,
  });
};

[ronalterya]

All the loaders run together, this won't work.

[gustavopch]

Also, the root loader doesn't always run when you navigate.

[kevlened]

@cliffordfajardo You should check authentication on every child route. If not, the children aren't protected.

It's not obvious when browsing normally, especially on first load, because the root loader has a chance to redirect. However, each child route is its own api. This becomes evident if you make a direct request to a child route (something like curl 'http://localhost:3000/some_child_route?_data=routes%2Fsome_child_route').

When a child's api is called directly, the root is never called, so the child happily returns the json needed by your frontend to anyone who asks for it.

[asacarter]

Having loaders run in parallel for speed is a neat idea but there are instances where a parent loader needs to pass data to a child loader.

IMO, there should be a setting to enable a specific parent route to load a child route sequentially and allow the transfer of loader data to get the best of both worlds.

It should be up to the developer of the application to choose if a route loads in parallel or sequentially.

[dangreaves]

An example use case for this feature is how Shopify themselves are using it in the Hydrogen template.

https://github.com/Shopify/hydrogen/blob/main/templates/hello-world/server.ts#L60

They are creating an API client in the custom server, and then attaching it to context using getLoadContext. That same API client is then shared throughout the entire app.

I would love to be able to do something like this in my own Remix apps, without needing to define a custom server, when all I need is a way to set context.

[panzerdp]

Agree. To me it is a strange design to attach the context from a custom server rather than directly from any parent route.

[sloonz]

I’m confused why a lot of people here think this is "urgently and importantly needed". We kinda have it already ? In the sense that we have an empty context object (empty if we haven't filled it with a load context) that is shared between loaders.

context.server.tsx :

export function getSession(request: Request, context: any): Promise<Session> {
  if(!context.session)
    context.session = sessionProvider.getSession(request.headers.get("cookie"));
  return context.session;
}

Any route loader :

import {getSession} from "./context.server";
export async function loader({request, context}: LoaderFunctionArg) {
  const session = await getSession(request, context);
  // ...
}

Sure, formalizing it would be a win, but this work-around seems sufficient in most cases ? What am I missing ?

[lithdew]

I can imagine server context being helpful in scenarios where you do not want or may possibly not be able to pass down request: Request across all parts of your application where you rely on context.session.

For example, say you have a global RPC client that is isomorphic (works both server-side and client-side). The RPC client would directly invoke the RPC function handler on the server side. The RPC client would make a fetch call to the server on the client side.

Here is an example with tRPC and vite-env-only:

const serverLink: TRPCLink<AppRouter> | undefined = serverOnly$(() => {
    return ({ op }) =>
        observable((observer) => {
            const ctx = getSessionContext();

            callTRPCProcedure({
                procedures: appRouter._def.procedures,
                path: op.path,
                getRawInput: async () => op.input,
                ctx,
                type: op.type,
            })
                .then((data) => {
                    observer.next({ result: { data } });
                    observer.complete();
                })
                .catch((cause) => {
                    observer.error(TRPCClientError.from(cause));
                });
        });
});

const clientLink: TRPCLink<AppRouter> | undefined = clientOnly$(
    httpBatchLink({
        url: "/trpc",
        transformer,
    })
);

export const trpc = singleton("trpc", () => createTRPCClient<AppRouter>({
    links: [
        ...(serverLink ? [serverLink] : []),
        ...(clientLink ? [clientLink] : []),
    ],
}));

Implementing this pattern would be convenient and simple with server contexts. I cannot see how this could work without having separate server-side/client-side client variables defined with the method you've shown.

Maintaining separate clients on the server and client introduces a lot of redundancy in a codebase. For example, with TanStack Query, for each query I define that I may prefetch on the server-side, and fetch on the client-side, I would have to define 2 separate client-side/server-side queryOptions.

In general, any kind of isomorphic global variable or function which conditionally may rely on some parts of the current request being handled (i.e. server actions, globally-defined Tanstack Query queryOptions, etc.) wouldn't be possible to implement I believe with the method you've shown.

For the time being, right now I'm using AsyncLocalStorage as a workaround instead (which means I'm using getLoadContext() as an escape hatch, which also means I am forced to define a custom server.ts).

[maranomynet]

The way Remix works currently, we should assume that parallel loader requests would typically land at different servers with different memory spaces

But single fetch is being worked on (#7640) so this will not continue to be an issue, right?

[kenn]

But single fetch is being worked on (#7640) so this will not continue to be an issue, right?

Yes!

If we can anticipate "single fetch" meaning a single HTTP request per navigation, we can keep all the context in the same request lifecycle in the same thread. It will make things dramatically simpler and better. I'm glad to hear Remix is headed to that direction!

[maranomynet]

If we can anticipate "single fetch" meaning a single HTTP request per navigation

That's exactly how I understood the single feetch feature to work, after listening to Ryan and Michael explain it during roadmap planning.

[ryan0x44]

Also worth adding here is that storing data against the context (or in any global) on Cloudflare Workers/Pages means that the data could be persisted across multiple requests when they land on the same workerd instance, which might not be the expected behaviour. Easy to demonstrate this in dev as the globals are persisted across all requests until dev server is restarted.

[sebasgarcep]

Maybe I am wrong but I am seeing two access patterns inside actions/loaders for the server context:

const action = () => {
  const { db } = getContext();
}
// and
const action = ({ context }) => {
  const { db } = context;
}

Are both valid or only one of these? I'm interested because the second access pattern would make testing easier (just set a property on an object before passing it to the action function).

[kiliman]

The context in your loader/action signature is from getLoadContext. It's difficult to say until the spec is more fleshed out, but according to Ryan...

It should replace the need for getLoadContext in adapters making it possible to share context abstractions between apps using different server adapters. It also enables context at the route level instead of the app level.

Server Context is supposedly different as you can export a context object in your route to add to the server context, or use it in middleware.

It's not clear if you only access server context via getContext() or if it will eventually be passed as the context in your loader (that would be a breaking change, so it would be a v3 feature/future flag).

[GiveMe-A-Name]

Have any progress? I would like to use serverContext. For us, we need a way to pass some vars by loader.context

[HananoshikaYomaru]

I don't think it is the focus of Remix anytime soon because it is still in the backlog on the roadmap

[ryanflorence]

Closing in favor of remix-run/react-router#11565