Request-scoped DI containers in App Router / RSC

[bezmen-e]

Hi! I’m experimenting with a small TypeScript dependency injection library and recently added a Next.js App Router / RSC adapter.

Library:
https://www.npmjs.com/package/di-craft
https://github.com/bezmen-e/di-craft

Next.js App Router docs section:
https://github.com/bezmen-e/di-craft#nextjs-app-router

The idea is to keep the core DI container framework-agnostic and expose Next-specific behavior through separate subpath exports.

The model is:

• create one root container on the server;
• create a child container per request/render;
• use React.cache as the request memoization primitive for RSC;
• keep React/Next out of the core package;
• avoid moving the DI container to the client;
• pass only serializable state snapshots from server state entities to client state entities.

So instead of this:

server DI container -> client DI container

it uses this:

server state -> serializable snapshot -> client state

The adapter also has an explicit helper for Route Handlers and Server Actions, where the request container can be disposed after the callback.

I prepared a small App Router demo that covers:

• Page / RSC request scope;
• nested Server Components;
• Route Handler;
• Server Action;
• parallel requests;
• client hydration from a server snapshot.

Demo source:
https://github.com/bezmen-e/di-craft-next-demo

Demo README:
https://github.com/bezmen-e/di-craft-next-demo#readme

Note: this demo is designed for a real local Node.js environment or Vercel deployment. StackBlitz/WebContainer environments may fail with current Next.js dev runtime limitations around Turbopack/Webpack fallback and RSC internals.

A few things I’m trying to validate:

1. Is React.cache the right primitive for request-scoped userland containers in RSC?
2. Is there a recommended lifecycle/disposal pattern for request-scoped resources after an RSC render?
3. Does the server state -> serializable snapshot -> client state model fit App Router boundaries well?
4. If state needs to be delivered gradually, is there a recommended direction for partial/streamed snapshots without turning this into a state manager?

This is not a request for framework integration. I’m mostly trying to validate whether this userland pattern is aligned with Next.js/RSC semantics.

I’d be happy to hear any feedback, corrections, or advice on this approach, especially around request lifecycle, disposal, and state snapshots in App Router/RSC.

[Ishant1302]

Your approach looks broadly aligned with how App Router and RSC are intended to work. Using react.cache() as the mechanism for creating a request-scoped container is a sensible choice because it provides request-local memoization and allows nested Server Components to share the same container during a render.
The strongest part of the design is keeping the DI container on the server and passing only serializable state snapshots to the client. That fits naturally with RSC boundaries and avoids the complexity of mirroring server-side services in the browser.
The main thing to be careful about is disposal. Route Handlers and Server Actions have clear lifecycle boundaries, so explicit cleanup there makes sense. However, React currently doesn't expose a reliable "render finished" hook for Server Components, so deterministic disposal after an RSC render is difficult to guarantee.
For progressive state delivery, I'd lean on React/Next.js streaming and Suspense rather than building a custom snapshot-streaming mechanism. Overall, the architecture feels well thought out, framework-friendly, and consistent with current RSC semantics.

[apoorva-01]

This is basically the right shape. cache() is exactly the primitive you want for a per-request container: it memoizes for the life of one server request and throws the cache away between requests, so "one child container per request" falls out for free without you tracking request IDs yourself. Nice fit.

Two things I'd flag before you lean on it too hard:

cache() only reaches the render tree. It dedupes within a single RSC render pass. Server Actions and Route Handlers don't run inside that tree, so a cache()-backed container won't be the same instance you get during render. If someone expects getContainer() in a Server Action to hand back the same child container the page used, it won't, and that's a fun one to debug at 2am. Worth calling out loudly in the docs.

AsyncLocalStorage is the complement, not the competitor. It's the other request-scoped primitive in Node, and it covers the spots cache() can't reach (middleware, route handlers, plain server code). It's less React-idiomatic and a bit more ceremony, but if you ever need one container that's truly consistent across render and actions and handlers in the same request, that's the tool. Might be worth a "when to reach for which" note.

The "only pass serializable snapshots to the client" rule is the right call and honestly the part people get wrong most, so good that it's baked in from the start.

[bezmen-e]

This is basically the right shape. cache() is exactly the primitive you want for a per-request container: it memoizes for the life of one server request and throws the cache away between requests, so "one child container per request" falls out for free without you tracking request IDs yourself. Nice fit.

Two things I'd flag before you lean on it too hard:

cache() only reaches the render tree. It dedupes within a single RSC render pass. Server Actions and Route Handlers don't run inside that tree, so a cache()-backed container won't be the same instance you get during render. If someone expects getContainer() in a Server Action to hand back the same child container the page used, it won't, and that's a fun one to debug at 2am. Worth calling out loudly in the docs.

AsyncLocalStorage is the complement, not the competitor. It's the other request-scoped primitive in Node, and it covers the spots cache() can't reach (middleware, route handlers, plain server code). It's less React-idiomatic and a bit more ceremony, but if you ever need one container that's truly consistent across render and actions and handlers in the same request, that's the tool. Might be worth a "when to reach for which" note.

The "only pass serializable snapshots to the client" rule is the right call and honestly the part people get wrong most, so good that it's baked in from the start.

Hi! Thanks for the detailed feedback.

I opened a follow-up PR based on your comments:
bezmen-e/di-craft#1

What changed:

• kept React.cache() as the primitive for RSC render scope;
• documented that Page/RSC containers are not shared with Server Actions or Route Handlers;
• updated Route Handler and Server Action examples to use an explicit request scope;
• added a separate di-craft/node adapter backed by AsyncLocalStorage for Node async contexts outside the RSC render tree;
• kept the client boundary as server state -> serializable snapshot -> client state.

The main split is now:

RSC render scope   -> di-craft/next/server -> React.cache()
Node async scope   -> di-craft/node        -> AsyncLocalStorage
Client boundary    -> serializable snapshots

Would be happy to hear if this boundary looks clearer now, especially the split between di-craft/next/server and di-craft/node.

[unusdon]

Adding a few things to what's been said, since I hit this pattern building a multi-tenant SaaS on App Router and had to work through the disposal + Server Actions story carefully.

React.cache is not enough on its own.

React.cache(fn) memoizes for the lifetime of a single render pass — meaning it dedupes within one page render and its child RSCs, and that's it. What it does not do:

• Survive across a Route Handler request → the render tree isn't involved.
• Survive across a Server Action invocation → same reason. Server Actions can call revalidatePath/revalidateTag which triggers a new render pass, but the container from the action's own execution is a different memoization scope.
• Give you a disposal hook. React has no "post-render" callback in RSC; whatever you .cache gets GC'd when the render is done, silently.

So React.cache works fine if your entire dependency graph fits inside "one RSC render." The moment you need the same container inside a Route Handler, a Server Action, or middleware, you need a second primitive.

AsyncLocalStorage is that second primitive.

Wire it once at the top of every entry point (middleware, route handlers, server actions) so every code path shares one shape:

// lib/container.ts
import { AsyncLocalStorage } from "node:async_hooks";

export type Container = { db: Db; s3: S3; tenantId: string };
export const containerStorage = new AsyncLocalStorage<Container>();

export const getContainer = () => {
  const c = containerStorage.getStore();
  if (!c) throw new Error("container missing — did you forget the wrapper?");
  return c;
};

Then a single wrapper you use everywhere:

// lib/withContainer.ts
export async function withContainer<T>(tenantId: string, fn: () => Promise<T>) {
  const container: Container = {
    db: makeDb(tenantId),
    s3: makeS3(tenantId),
    tenantId,
  };
  try {
    return await containerStorage.run(container, fn);
  } finally {
    // disposal — the piece React.cache doesn't give you
    await container.db.[Symbol.asyncDispose]?.();
    await container.s3.[Symbol.asyncDispose]?.();
  }
}

Now inside RSC, Route Handlers, and Server Actions the code is identical:

export async function POST(req: Request) {
  const tenantId = await resolveTenant(req);
  return withContainer(tenantId, async () => {
    const { db } = getContainer();
    // ...
  });
}

// server action
"use server";
export async function createPost(input: FormData) {
  const tenantId = await resolveTenantFromSession();
  return withContainer(tenantId, async () => {
    const { db } = getContainer();
    await db.insert(posts).values(fromForm(input));
    revalidateTag(`t:${tenantId}:posts`);
  });
}

Combine with React.cache for RSC-only speedups.

Inside a render pass, React.cache still earns its keep for dedupe:

// inside RSC
const listPosts = cache(async () => {
  const { db } = getContainer();
  return db.select().from(posts);
});

Two RSCs on the same page calling listPosts() share the result. AsyncLocalStorage handles cross-request coherence; React.cache handles intra-render dedupe. They compose cleanly.

Two footguns that will bite you.

1. Don't pass the container to the client. Client components can't use AsyncLocalStorage and don't need the container — pass serialized snapshots across the RSC → Client boundary. If you ever find yourself wanting to use(containerPromise) from a client component, that's a smell that you're about to leak.
2. Streaming + Suspense interact well with this, but be careful about unstable_after. If you're on Next 15 and want side effects after a Server Action commits, unstable_after runs outside the AsyncLocalStorage.run scope — you have to re-enter it manually, or hoist your logging out.

tl;dr — React.cache alone doesn't model DI, it models memoization. Wrap every entry point in one AsyncLocalStorage.run-based wrapper for the container, put disposal in finally, and use React.cache on top for intra-render dedupe. That's the shape that survives Route Handlers, Server Actions, and multi-tenant boundaries without duct tape.

[bezmen-e]

@unusdon thanks a lot for the detailed write-up. This helped clarify the boundary I needed to make more explicit.

I opened a follow-up PR here: bezmen-e/di-craft#2

What changed:

• clarified that the Next/RSC adapter is RSC render-scoped, not a full request lifecycle abstraction;
• documented that React.cache() is useful for render-pass memoization/dedupe, but does not cover Route Handlers, Server Actions, middleware-like code, or deterministic disposal;
• added an explicit ALS-first Next Node runtime section using di-craft/node;
• added a typed example showing the pattern you described: wrap the entrypoint with runWithRequestContainer(), then let deep async code call getRequestContainer() without threading the container through every function;
• included scoped resource cleanup via onDispose;
• added a warning for detached/post-action work, including unstable_after-style callbacks: anything that runs after the explicit async scope has settled should receive plain data or enter a new scope before calling getRequestContainer();
• kept the client boundary as serializable snapshots/plain data only.

I intentionally kept di-craft/next/server and di-craft/node separate:

• di-craft/next/server + React.cache() = RSC render scope;
• di-craft/node + AsyncLocalStorage = request/tenant context and deterministic cleanup;
• client boundary = serializable snapshots/plain data.

So React.cache() remains the RSC render-scope primitive, while AsyncLocalStorage owns request/tenant context and cleanup in Node runtime entrypoints.

Would be happy to hear if this split matches the shape you had in mind.

[unusdon]

Yes — this split is exactly the shape I had in mind, and the way you've drawn the boundary between di-craft/next/server + React.cache() and di-craft/node + AsyncLocalStorage is cleaner than how I usually explain it. Two small refinements you might want to bake into the docs while you're there:

1. unstable_after re-entry pattern. In Next 15+, if a Server Action queues work with unstable_after, that callback runs after the ALS scope has already settled — so getRequestContainer() inside it will throw. The idiomatic fix is to capture the primitives the callback needs before scheduling, then re-enter a fresh minimal scope for the deferred work:

"use server";
export async function publishPost(input: FormData) {
  return withRequestContainer(async () => {
    const { db, tenantId } = getRequestContainer();
    const post = await db.insert(posts).values(fromForm(input)).returning();

    // capture what the deferred job needs — don't rely on ALS post-await
    const capturedTenantId = tenantId;
    const capturedPostId = post[0].id;

    unstable_after(async () => {
      await withRequestContainer(async () => {
        // fresh scope; ALS re-populated for this callback
        const { search } = getRequestContainer();
        await search.index(capturedTenantId, capturedPostId);
      }, { tenantId: capturedTenantId });
    });

    revalidateTag(`t:${tenantId}:posts`);
  });
}

Worth calling out in the "detached/post-action work" section — this is the concrete API shape most people will trip over.

2. Edge runtime caveat. di-craft/node + AsyncLocalStorage cleanly implies Node runtime. Worth an explicit note that on the Edge runtime (middleware, export const runtime = "edge" Route Handlers), node:async_hooks is polyfilled but the semantics are subtly different — the polyfill can lose context across some awaits in edge workers. Recommend readers stick with the Node runtime for the ALS path, or use an equivalent Edge-native context primitive if they need Edge. Otherwise people will copy the pattern verbatim, deploy with runtime = "edge", and hit intermittent "container missing" errors that are hard to diagnose.

3. Testing footnote. For the vitest side of things, withRequestContainer composes nicely with a per-test container override — beforeEach(() => runInContainer(makeTestContainer(), () => ...)) works out of the box because AsyncLocalStorage handles the nesting for you. Might be worth a one-liner in the README so people don't reach for vi.mock-based DI which is where things get painful.

The three-layer separation you settled on (render-scope / request-scope / client boundary) is the shape that actually holds up under production load. Nice work on the follow-up PR.

[bezmen-e]

@unusdon thanks again, these are great follow-up points.

I added another small docs update to the PR:

• documented the unstable_after / deferred-work case with the concrete pattern you described: capture primitive values before scheduling, then re-enter a fresh minimal runWithRequestContainer() scope inside the deferred callback;
• expanded the Edge runtime caveat for the ALS path: di-craft/node should be treated as a Node runtime adapter, and Edge users should pass context explicitly or use an Edge-native context primitive;
• added a testing note showing per-test runWithRequestContainer() with test-only providers, so deep code can still use getRequestContainer() without reaching for module mocks.

I also clarified in the examples that getRequestContainer() and runWithRequestContainer() are app-configured helpers returned from createNodeDi() and re-exported from an app-local composition module, not top-level imports from di-craft/node.

That should cover the three footguns you called out while keeping the runtime API unchanged.

[unusdon]

That covers all three cleanly. Nice on the follow-up PR — the split between di-craft/next/server + React.cache() (RSC render scope) and di-craft/node + AsyncLocalStorage (request/tenant + disposal) is exactly the boundary that holds up under production load. Happy to reference this thread when the next multi-tenant Server Actions question comes up.

[bezmen-e]

Thanks a lot, really appreciate your time and the thoughtful feedback.

Your comments helped make the docs much more grounded in real production usage, especially around Server Actions, ALS scope, disposal, and the Edge/runtime caveats.

If you have any other ideas for improving the library or directions worth exploring, I’d be very happy to hear them.

[GLima-n]

One additional area I'd consider documenting is how the container behaves during aborted or partially completed streaming renders.

The distinction between render-scoped memoization and explicitly managed request scopes is clear in your updated design.

A useful next step could be a small integration test matrix covering:

• Two concurrent requests with different tenant contexts.
• A streaming render interrupted before completion.
• A Server Action that fails after acquiring a scoped resource.
• A deferred callback that starts a fresh scope after the original action completes.

For explicit scopes, the tests could assert that cleanup runs exactly once, including failure paths.

For RSC render-scoped containers, I'd avoid promising deterministic disposal unless the framework provides an appropriate lifecycle guarantee.

This would make the lifecycle limitations observable rather than only documented.

Have you already included cancellation or interrupted-stream tests in the demo?