Next.js: Using Node.js modules in Edge Runtime (Proxy or Middleware)

What it means in plain English

Next.js's Using Node.js Modules in Edge Runtime page says this error occurs when the code in your Proxy or your Edge API Routes uses a feature from the Node.js runtime. The Edge Runtime does not support Node.js APIs and globals.

Proxy is the new name for the middleware file. Next.js's Proxy page has a version history: Middleware could use the Node.js runtime as an experiment from v15.2.0 and as a stable option from v15.5.0. In v16.0.0, Middleware was deprecated and renamed to Proxy, and Proxy defaults to the Node.js runtime. So this error mostly shows up in Middleware or Edge API Routes that run in the Edge Runtime, when they or anything they import use a Node.js-only module.

Likely causes

• The Proxy or Middleware file imports a Node.js module, such as crypto, directly.
• It imports a helper or package that uses a Node.js module somewhere inside.
• An Edge API Route uses a Node.js API.

How to fix it, step by step

1. Run the app locally with next dev. Next.js says the console and the browser show which file is importing and using the unsupported module.
2. Follow that file chain back to the Proxy, Middleware, or Edge API Route that imports it.
3. Avoid the module there. Next.js's two options are to stop importing it, or to replace it with a polyfill.
4. Where a Web API can do the job, use it. Next.js's example is replacing the Node.js crypto module with the Web Crypto API.
5. If you need Node.js APIs in that file, check the version history on Next.js's Proxy page against your Next.js version. Proxy, from v16.0.0, defaults to the Node.js runtime, and Next.js says the runtime config option is not available in Proxy files.
6. Check Next.js's Edge Runtime page for the list of supported and unsupported APIs before adding another import to that file.
7. Run next dev again and confirm the error is gone, then rebuild.

How to check it worked

• next dev no longer reports a Node.js module in the Edge Runtime.
• Requests that pass through the Proxy or Middleware work in production.

Sources

• https://nextjs.org/docs/messages/node-module-in-edge-runtime (opens in a new tab)
• https://nextjs.org/docs/app/api-reference/file-conventions/proxy (opens in a new tab)