RFC: "registerAfterEnv" hook for "instrumentation"

[kettanaito]

Goals

1. Allow third-party packages to patch global fetch.
2. Have a manageable, framework-provided way to execute server-side side-effects in Next.js.

Non-Goals

No response

Background

With the Next 13 release, Next has irreversibly removed the means to execute server-side side-effects, such as patching global fetch function or the http module. Previously, that could be achieved by executing those side-effects in _app.js, but the new release has no corresponding API to replace _app in that regard.

Although this issue surfaces from MSW (mswjs/msw#1644), it's a much broader problem since the current Next behavior doesn't allow for any libraries to establish server-side side effects.

When I originally started the discussion around this, Next used to have two development processes, which made the server-side effects introduction all the more challenging. Since then, I believe there have been some improvements, and the internal server structure has been reworked to keep just one Node.js process, which is beneficial.

Potential solutions

Let's discuss potential solutions to this problem using the existing state of Next, and see why they aren't fit to adequately solve it.

Using the instrumentation hook

The instrumentation hook is great but its register function runs before Next patches the global fetch, making it impossible to establish and persist any patches on the function.

Using globalThis._nextOriginalFetch

Next.js seems to preserve whichever state of the fetch was before the internal patching and apply the patch to that state. While this sounds like a perfect solution, it's anything but. Here are some of the disadvantages this approach has:

1. _nextOriginalFetch is a Next-specific internal flag. No third-party consumers should depend on such implementation details, it's unsafe.
2. Third-parties shouldn't ship a framework-specific code if those third-parties aren't framework-specific themselves; this is simply a wrong surface to tackle the problem.

Using testing integration in Next.js (#53409)

While this is a great endeavor, it seems to address the problem at the wrong level.

1. The inability to establish side-effects has no direct connection to testing.
2. If talking about API mocking libraries, they can be used for far more purposes than testing on a particular level. The whole idea of tools like MSW is to elevate the network description and allow the developers to reuse mocks across the entire stack. That is possible if the tools don't lock the mocking functionality under a particular feature or use case, like it's been historically. That's kind of what this solution implies and I'm against it.
3. The implementation of the solution also strongly suggests we are approaching the horse from the wrong end (excuse me for the metaphor here).

Proposal

I propose to utilize the existing instrumentation hook. In its current form, the register function it supports still runs before Next.js patches fetch, so whichever modifications a third-party module may establish will be discarded.

Instead, I propose something like registerAfterEnv (better names are welcome), which is a new phase that Next will run as the very last thing after it has prepared its environment (e.g. patched the fetch). I also take the current decision to patch fetch in Next as something you are choosing to stay with despite its apparent downsides and generally harmful experience for both Next users and third-party library authors shipping things for Next.

// instrumentation.js
export function registerAfterEnv() {
  console.log(fetch) // FetchPatchedByNext
  globalThis.fetch = patchFetchInAnyWay(fetch)
}

Perhaps the instrumentation hook being experimental is a great time to discuss this. Please, let's make this happen. Thank you.

[feedthejim]

@kettanaito Hey, thanks for writing this up. Great way of starting a productive conversation :). I also agree that adding an API to the instrumentation hook would be the best solution for your use case.

Whilst it probably won't come in the shape of registerAfterEnv as there's no clear boundary in Next.js of when the "env" is fully set up, I was planning on adding an onRequest hook that would allow you to run some logic immediately before processing a request, similarly to a middleware but for instrumentation. I believe that fetch would be patched at this point and that you could then add your own layer of monkey patching there :).

I don't have a clear estimate on when I would get around to doing so though.

[edmolima]

Hey @jviall @kettanaito Did you guys deal with it? I mean, Is there some alternative that you are using until somehow the vercel team responds about this officially proposed RFC?

[kettanaito]

@edmolima, some folks are moving the MSW request handlers into a standalone server using @mswjs/http-middleware (mswjs/msw#1644 (comment)) and then routing the app's traffic through it. This will work since it negates the need to intercept anything but keep in mind this approach negates the main benefits of MSW.

There are no other workarounds here because of how Next.js behaves at the moment.

[kmiwa007]

Just chiming in support that Next needs make MSW happen!

[rkofman]

@feedthejim (or others at Vercel): is there by any chance a rough timeline for when a version of Next.js will be released that doesn't override fetch, and therefore works well with msw (and others)?

[rmiller61]

Would also like to second this. The inability to easily mock APIs has become a major wedge issue for considering Next in my projects.

[Geminii]

@feedthejim Any update on this topic ? 🙏
Christmas before Christmas ? 😍

[kettanaito]

I don't think it's reasonable to expect the team to release an experimental Cache API before the holidays. Let people rest. I've seen some code snippets of the experimental Cache API in the wild, so I assume it's there and the effort is ongoing. In a few months, perhaps?

[Geminii]

Glad to heard, thanks for quick update 🙂
Happy holidays and see you next year 🎄

[AndrewIsh]

Is progress on this still being tracked here? Is there any progress? :)

[SalahAdDin]

Another important issue being left part by Vercel, is it the time to move to another framework?

[chrisb2244]

With respect to the issue described specifically for fetch, a recent(ish) patch (maybe a month or a month and a half ago) changed Next's behaviour here - patched fetch is preserved now (and you can use MSW for server-side code).

It's still a little confusing given your nextjs code can run in various places and if you want to intercept them all, you'll need a combination of worker/server MSW setups, but you can of course reuse the handlers.

[rmiller61]

With respect to the issue described specifically for fetch, a recent(ish) patch (maybe a month or a month and a half ago) changed Next's behaviour here - patched fetch is preserved now (and you can use MSW for server-side code).

It's still a little confusing given your nextjs code can run in various places and if you want to intercept them all, you'll need a combination of worker/server MSW setups, but you can of course reuse the handlers.

Do you have a working example? AFAIK the cache APIs aren't stable.

[chrisb2244]

If the goal is only to provide interception with static handlers, then I believe Artem's example here is perhaps working?
mswjs/examples#101

I have an example repo that I started on here (https://github.com/chrisb2244/msw-nextjs-example) but I'm currently waiting to see if a PR gets merged (mswjs/msw#2041) before I return to it (if I recall correctly, I was fairly happy with the server-side fetches and the remote server control for testing (working together with static handlers, if desired), but the client-side stuff left something to be desired (probably because it's been too long since I tried to put Playwright and MSW together, and I've forgotten the key points)).

I'll be going back to that example if I can in the future to try and test out various behaviours, in part for my own sanity, testing in a simple project before trying to apply the same to a real repository (where I'd be less sure that any failures weren't just my code being exercised in ways I hadn't expected... :/ )

[SalahAdDin]

@chrisb2244

If the goal is only to provide interception with static handlers, then I believe Artem's example here is perhaps working.
mswjs/examples#101

No, it does not work. MSW is unable to intercept the request.