HMR in Next.js monorepos: procedures use stale code at runtime when workspace changes are made

[inducingchaos]

Environment

Next.js: 16.0.8
oRPC: 1.12.2
pnpm: 10.20.0
Node.js 22.20.0

Reproduction

https://github.com/inducingchaos/code-reproductions/tree/orpc-nextjs-monorepo-hmr-staleness

Describe the bug

See the reproduction README for more details.

Basically, whenever you make changes on the backend, Turbopack does not recompile them and you end up with your dev server running code that doesn't physically exist in your codebase.

What I've figured out (disclaimer: I don't know much about bundlers or how object references work):

• I don't think it's a transpilePackages issue, since the app dir bundles dependencies automatically (see Documentation: transpiling step seems not necessary with the pre-installed Next.js application vercel/turborepo#7058 (comment))
• AI thinks that "The issue is that client.ts uses const client = globalThis.$client ?? createORPCClient(link), which captures the reference at module initialization. When HMR updates globalThis.$client in client.server.ts, the client const in client.ts keeps the old reference because that module doesn't re-evaluate." However, this initialization pattern is the exact one recommended in https://orpc.dev/docs/adapters/next#optimize-ssr - and I recall it working before.
• This only seems to affect API routes that consume the API client. Pages/components that use it seem to HMR correctly.

I found a lot more nuanced details while testing, but how the project constructs the dependency/import graph really affects it (e.g., at some point saving the router file logged v2 at the module level but not in the handlers, as well as updating the Next.js API endpoints would trigger the handler code to be successfully updated). Because of this, it's really hard to provide concrete facts about the issue.

I've been trying to resolve this since Tuesday evening with Opus 4.5 and finally got it working in my main app using a Proxy instance (thanks to the idea from https://github.com/unnoq/orpc/discussions/744), but wasn't able to get this solution to work in the repro.

Any ideas?

Additional context

No response

Logs

[dosubot]

This HMR staleness is caused by how Turbopack and Next.js handle module caching for API routes: when you use const client = globalThis.$client ?? createORPCClient(link) (the recommended oRPC SSR pattern), the client reference is captured at module initialization. If HMR updates globalThis.$client, the client variable in modules that already imported it doesn't update, so you get stale references in API handlers. This doesn't affect page components as much because their HMR boundaries and reload logic are different and often more granular.

The oRPC docs don't mention HMR-specific handling or workarounds for this pattern—it's a general Node.js/SSR optimization, not HMR-aware. The Proxy workaround you found is a community solution: by wrapping the global reference in a Proxy, you force re-evaluation on every access, so you always get the latest client after HMR updates. This approach is discussed in detail in oRPC Discussion #744.

There aren't any official config tweaks or code changes in oRPC or Next.js that solve this at the framework level. The issue is fundamentally about module-level reference capture and how Turbopack's HMR doesn't always re-evaluate API handler modules when their dependencies change. Disabling Turbopack resolves some related issues, but that's not always practical.

To minimize staleness: use the Proxy workaround for any shared references that need to stay fresh during development, and structure your imports so that server-only code is kept out of shared modules (see SSR best practices). If you need per-request context, avoid global state and consider dynamic imports or runtime guards. There isn't a more "official" solution right now—this is a known limitation of the current HMR/module system in Next.js 16 + Turbopack with oRPC.

If you want to track the evolution of this workaround or see more examples, check out the discussion here and the docs here.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[unnoq]

Could you create another reproduction based on the oRPC playground? The current playground setup is quite messy. While the issue can be reproduced, the setup itself is not standard.

That said, this problem does not appear to be related to oRPC at all (it's purely a JavaScript library). It's possible that Next.js does not fully support this pattern. You could consider disabling it during development and enabling it only in production, or simply avoid using this pattern altogether.

[inducingchaos]

Could you create another reproduction based on the oRPC playground?

Edit: I deeply considered creating another repro in one of the oRPC playgrounds - but after realizing that the Next.js Playground isn't a monorepo (may or may not matter) and the Multiservice Monorepo Playground doesn't include a Next.js app, I decided not to. I spent many hours just to reproduce this cleanly... it is very minimal and does the job perfectly fine.

The current playground setup is quite messy.

I'm not sure how the repo could be perceived as messy, although organization is subjective so I'll dismiss that comment.

While the issue can be reproduced, the setup itself is not standard.

How so? According to the oRPC docs:

• Server-side clients are a very common use case for RPC clients, and the Next.js API folder is the default place to build server-side functionality (aside from server components): https://orpc.dev/docs/client/server-side#router-client
• Our client setup is identical to the one described in https://orpc.dev/docs/best-practices/optimize-ssr

The only thing I could see being non-standard is the eventIterator, but that shouldn't effect the reproduction.

That said, this problem does not appear to be related to oRPC at all (it's purely a JavaScript library)

Sure, it's just a library - but oRPC is also build on TypeScript, as well as advertised to support Next.js.

I would argue that it could, and should be handled on oRPC's end because:

1. The docs promote this pattern, and will confuse users when they run into this issue
2. Although upstream bugs are possible (Node.js, Turbopack, Next.js), I believe (you may not - and that's totally okay) that if a library author is considering issues of any sort, our job as maintainers is to manage and work around the quirks of upstream deps IF the issue falls within the main scope of the library (e.g., oRPC helps build type-safe APIs - HMR should be a given) and its supported counterparts (e.g., Next.js). So long before we write this off as a Turbopack issue - we should suggest against using Turbopack/Next.js, if this is an inevitable architectural problem (which I don't think it is). TL;DR: It's us, not them - unless it's actually a bug on their end, and not by design.
3. I don't think it has to do with Turbopack/Next.js at all, since the issue can be fixed by changing client.ts to use the following code without changing any dependencies or import patterns:

declare global {
    var $client: RouterClient<Router> | undefined
}

const isServer = typeof window === "undefined"

function getClient(): RouterClient<Router> {
    if (isServer) {
        if (!globalThis.$client) throw new Error("Server client not initialized.")

        return globalThis.$client
    }
    throw new Error("Network link not implemented.")
}

/**
 * @remarks Workaround for issue: https://github.com/unnoq/orpc/issues/1346
 */
const clientProxy = new Proxy({} as RouterClient<Router>, {
    get(_, prop) {
        const client = getClient()

        return Reflect.get(client, prop, client)
    },

    has(_, prop) {
        return Reflect.has(getClient(), prop)
    },

    ownKeys() {
        return Reflect.ownKeys(getClient())
    },

    getOwnPropertyDescriptor(_, prop) {
        const client = getClient()

        const descriptor = Object.getOwnPropertyDescriptor(client, prop)
        if (descriptor) return { ...descriptor, configurable: true }

        return undefined
    }
})

export const api = createSafeClient(clientProxy)

4. Another user was experiencing the same problem in a different framework (https://github.com/unnoq/orpc/discussions/744), making the issue framework-agnostic and more likely a more fundamental Node.js/TypeScript issue.

It's possible that Next.js does not fully support this pattern

Possibly... the client.server.ts is something I've only seen once or twice, so there could be edge cases. But if you're suggesting Next.js doesn't support transpiling monorepo packages or consuming them in the ./src directory or API route handlers, I don't think that's the case.

You could consider disabling it during development and enabling it only in production, or simply avoid using this pattern altogether

Correct me if I'm wrong - but wasn't the "pattern" in question the entire reason oRPC was created? To share API types within a monorepo or server/client boundary with the intention to optimize DX (which implies that hot reloading still work)?

What are you suggesting that I disable in this case? (although we shouldn't have to disable anything)

Takeaways

Now that I've addressed your points, I'd love if we could work towards a solution that would benefit the framework. I don't mean to be brash in my responses but the response you gave felt more like criticism of my repo and less of working to resolve the problem.

I do love oRPC, and hope that someone with more low-level JavaScript knowledge than me can help resolve whatever stale object binding issue or module resolution quirk is happening here.

Maybe that means changing how router objects are derived under the hood - or changing the docs to suggest a different initialization pattern.

Have a great night.

[unnoq]

First of all, thanks for your effort on this issue.

but after realizing that the Next.js Playground isn't a monorepo

For minimal repro, and easier debug - you should re-create issue on monolith setup

I'm not sure how the repo could be perceived as messy

1. There no RPCHandler in your repro
2. You use oRPC client in another next.js apis route while it should be called from server or client components
3. you might missing import .server.ts in root layout

I still think you’re attributing this problem to JS/TS/Node/oRPC, but that's not correct. Issues like HMR are introduced by the bundler, not by the JavaScript or TypeScript code itself. If you’re hitting this problem, it should be raised with the bundler - it's either a bug or a known limitation.

The solution you're using is effectively a workaround for how the bundler treats your code, rather than a fix for an issue in oRPC or the underlying runtime. (but thanks it still valuable for community)

If you can demonstrate that this pattern does not work properly in Next.js, I'm more than happy to update the documentation to reflect that. However, based on my own testing and using oRPC, everything works as expected.

[unnoq]

After testing again, I believe this issue only happens when using the oRPC client inside Next.js route.ts files (works well in client/server react components). It only updates when the route.ts file itself changes.

Maybe related to Vercel optimization where each route.ts file has its own bundle (maybe abit different than react components - so can be a bug rathan expected behavior)

[inducingchaos]

Hmm, it may be worth opening an issue with Vercel then. Definitely a frustrating one... will work around it for now.

Thanks for taking the time to look into it.