Support Next.js 13 (App Router)

[kettanaito]

Scope

Adds a new behavior

Compatibility

• This is a breaking change

Feature description

As of 1.2.2, MSW does not support the newest addition to Next.js being the App directory in Next.js 13. I'd like to use this issue to track the implementation of this support since many people are currently blocked by this.

Prior investigation

I looked into this a month ago and discovered that there's difficulty to establish any process-wide logic in Next.js 13 due to the way Next itself is implemented internally. Very briefly, Next keeps two Node.js processes while it runs:

1. One process is persistent (opened once on the same port and running there).
2. Another process spawns at a random port, does its job, and gets killed.

This process separation is evident when you issue a hot reload to any of the layout components.

Reloading a root layout

When a hot update is issued through the root layout component, we can see the persistent Node.js process update. I don't remember any changes to the intermittent process.

Reloading a nested layout

When a hot update is issued for a nested layout, i.e. a certain page's layout, the intermittent process gets killed, then a new one spawns at its place (on a different port), likely evaluates the update, and keeps pending.

What's the problem with the two processes then?

In Node.js, MSW works by patching global Node modules, like http and https. Those patches must persist in the process in order for the mocking to work. Since Next uses this fluctuating process structure, it introduces two main issues:

1. We cannot establish the global module patches once since Next's functionality is split across two different, unrelated processes. Usually, the module patching should be done somewhere in your root layout since it's conceptually guaranteed to be the highest hot update point no matter where you are in your application. That's not the case in Next.js, as the processes evaluating the root layout and individual page layouts are completely different, and the module patches in one process do not affect the other.
2. Since the page-oriented (fluctuating) process constantly gets killed and spawned at random ports, I don't see a way to establish module patching in it at all to support API mocking for server-side requests issued in individual pages (or their layouts).

What happens next?

MSW is blocked by the way Next.js is implemented internally. I don't like this state of things but that's what we get—patching Node globals is not the most reliable of things and it will, inevitably, differ across frameworks depending on how those frameworks are implemented.

I would pretty much like for the Next.js team to assist us in this. There's very little we can do on the MSW's side to resolve this. In fact, I believe there's nothing we can do until there's a way to establish a module patch in Node.js for all Next.js processes at the same time.

If you're blocked by this, reach out to the Next.js team on Twitter or other platforms, letting them know this issue is important. I hope that would help the team prioritize it and help us resolve it together. Thanks.

[kettanaito]

It's also worth mentioning that this is not an issue with MSW. The library works in an extremely straightforward way in any browser or Node.js process. This issue is here simply to track the progress of this Next.js integration as many developers have voiced their concerns and questions about it.

[sebmarkbage]

Does it need to have a persistent process for some reason or can it just repatch each time if there was a place to do it?

How did this work in Next.js Pages for API routes since _app.js doesn’t run for those?

A workaround is to just have a module that’s imported from every layout, page or custom route that uses data. Such as in a share api layer:

import “./patch-msw”;

export async function getData() {
  return fetch(…);
}

We’re considering a global place to inject it too but not sure the process can be guaranteed to live on forever. That’s pretty limited.

[kettanaito]

@sebmarkbage, hi 👋 Thank you for reaching out!

Does it need to have a persistent process for some reason or can it just repatch each time if there was a place to do it?

It can certainly re-patch on every hot update. We are doing precisely that for Remix and Svelte examples. I had trouble doing that with Next due to those dual processes running (a Node.js patch on the root layout doesn't apply to the server-side logic of individual pages since those seem to be evaluated in a different process).

How did this work in Next.js Pages for API routes since _app.js doesn’t run for those?

I suppose it was fine because the main use case is to support client- and server-side development of Next apps, which came down to:

• Intercepting requests in the browser (that's handled by the service worker);
• Intercepting server-side requests made in getServerSideProps (and similar), and these abode by _app.js so it was enough to patch Node modules there to enable API mocking.

Right now, the second one doesn't work due to the lack of _app.js alternative in Next 13.

A workaround is to just have a module that’s imported from every layout

I have two concerns regarding this workaround:

1. This implies the imported code has some deduplication built-in so that the Node globals aren't patched by each individual import. We do have this logic present but it's still worth mentioning.
2. This has negative DX implications since the developer is, effectively, forced to collocate API mocking with individual resource-fetching areas (i.e. a specific page route), which degrades overall experience when compared to the very same setups in other frameworks.

We’re considering a global place to inject it too but not sure the process can be guaranteed to live on forever. That’s pretty limited.

It would be really nice to have _app.js, or similar—a designated place to establish client/server-side logic once and have it encapsulate all the future layouts/routes/etc. I understand this may be challenging based on Next's internals at the moment. If I can help somehow, just let me know.

[sebmarkbage]

We already have instrumentation.ts https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation

There's an idea to expand that to include more features and to have different variants for the different module/scopes processes so that it can patch the module in the Server Components scoped, SSR scope and Client side scope.

Not sure if what is already there might be sufficient for your use case.

[kettanaito]

Thanks, @sebmarkbage. At first glance, it looks like it could work. I will give it a try in a new Next example repository and let you know.

[kettanaito]

@sebmarkbage, do you know if the instrumentation.ts hook supports ESM? It doesn't seem like it does:

// ./with-next/instrumentation.ts
export async function register() {
  // I've tried a regular top-level import, it matters not.
  const { server } = await import('./mocks/node')
  server.listen()
}

Module not found: Package path ./node is not exported from package /new-examples/examples/with-next/node_modules/msw (see exports field in /new-examples/examples/with-next/node_modules/msw/package.json)
> 1 | import { setupServer } from 'msw/node'
  2 | import { handlers } from './handlers'
  3 | 
  4 | export const server = setupServer(...handlers)

While with-next/node_modules/msw/package.json is:

{
  "exports": {
    "./node": {
      "browser": null,
      "types": "./lib/node/index.d.ts",
      "require": "./lib/node/index.js",
      "import": "./lib/node/index.mjs",
      "default": "./lib/node/index.mjs"
    },
  }
}

My first hunch was maybe the hook runs in the browser too, thus it's unable to resolve the exports['./node'].browser import field. But it doesn't seem to run in the browser.

This is really odd because MSW doesn't ship ESM exclusively, it comes as a dual CJS/ESM package, which means it has both the exports (for modern browsers) and root-level stubs like ./browser/package.json and ./node/package.json to support older ones.

You can reproduce this behavior in here: https://github.com/mswjs/examples-new/pull/7

What can be going wrong here?

[kettanaito]

I strongly suspect Next.js is trying to resolve the browser field when encountering Node.js export paths in instrumentation.ts for some reason. If I provide a dummy stub for exports['./node'].browser, it will pass the module resolution.

Moreover, it then fails on a bunch of other 4th-party imports (msw -> @mswjs/interceptors) that have Node.js-specific export fields. This doesn't seem right.

Do I have to mark the imported module in instrumentation.ts as Node.js-oriented so Next.js knows about it? Looks redundant, given instrumentation.ts is for server instance bootstrapping. It shouldn't even be reaching out to the browser exports field.

[louis-young]

Hi 👋

Firstly, thanks for the fantastic library.

I don't know if this is something that you're already aware of, but MSW doesn't appear to work with Next.js 13 full stop, not just with the app directory. It doesn't appear to work with the pages directory; the official example is also broken.

Is the issue with the pages directory encapsulated by this issue too?

Thanks 😄

[kettanaito]

Hi, @louis-young. Thanks for reaching out.

I'm aware of the library not working with Next 13 in general (I believe there are also issues on Next 12; I suspect there were some architectural changes merged to Next 12 prior to Next 13 which may have caused this).

However, to reduce an already complex issue, I'd like to track the App router exclusively here and approach it first. As I understand, the App router is the main direction the Next is going to take, and pages remain there mainly for backward compatibility reasons (the App router is far too big an endeavor not to be the main thing in 1-2 releases, eventually).

[louis-young]

Thanks for getting back to me so quickly.

That's fair enough and a very reasonable and pragmatic approach, I just wanted to check that it was something that you were aware of.

Thanks again and keep up the great work 😄

[jmcpeak]

@louis-young We have msw working with the pages directory just fine. Make sure you have this code at the top of your pages component's index.tsx:

if (process.env.NEXT_PUBLIC_API_MOCKING === 'enabled') {
  // eslint-disable-next-line global-require
  require('@/mocks');
}

[darrylblake]

You can create a client side only component that you include in your root layout.tsx.

"use client";
import { useEffect } from "react";

export const MSWComponent = () => {
  useEffect(() => {
    if (process.env.NEXT_PUBLIC_API_MOCKING === "enabled") {
      // eslint-disable-next-line global-require
      require("~/mocks");
    }
  }, []);

  return null;
};

edit: sorry I mistakenly assumed not working "full stop" meant client side too

[kettanaito]

@darrylblake, that would work but the main thing we're trying to solve here is the server-side integration.