RFC: Switchable Next.js Runtime

[shuding]

Motivation

Next.js has two server runtimes to run your application: the Node.js Runtime (default) and the Edge Runtime. When doing SSR, or serving API routes, the application code will be executed in the Node.js Runtime; and for Middleware, it will be running in the Edge Runtime.

There are many differences between these two runtimes. Here’s a quick comparison:

	Node (server)	Node (lambda)	Edge
Cold Boot1	/	~250ms	Instant
HTTP Streaming2	Yes	No	Yes
IO	All	All	fetch
Scalability	/	High	Highest
Security	Normal	High	Highest
Latency	Normal	Low	Lowest
Code Size	/	50MB	1MB
NPM Packages	All	All	A smaller subset

Next.js' default runtime configuration is good for most use cases, but there’re still many reasons to change to one runtime over the other one. For example, to enable React 18’s streaming SSR feature, you cannot deploy the app to lambda. For API routes that relies on native Node.js APIs, it has to be running in the Node.js Runtime. But if an API only uses a simple cookie-based authentication, using middleware and the Edge Runtime will be a better choice due to its lower latency as well as better scalability.

In a real-world application, it will be very helpful to have the ability to customize the runtime for each Next.js route, for both pages and API routes.

Terminologies Used in This RFC

• getServerSideProps, gSSP, the Next.js API for SSR data-fetching
• getStaticProps, gSP, the Next.js API for SSG and ISR
• getInitialProps, gIP, legacy API for data-fetching in SSR
• React 18 Suspense-based SSR
• Automatic Static Optimization
• API Routes

Proposal

1. Global Runtime

A runtime option in next.config.js, which can be either nodejs or edge (or leave it as undefined):

module.exports = {
  experimental: {
    runtime?: 'nodejs' | 'edge'
  }
}

The value stands for the preferred global runtime for Next.js to use for SSR (gSSP-based SSR, Suspense-based SSR), SSG and API routes. If the option is missing, Next.js will automatically choose the runtime based on the type of each page (see "What’s happening under the hood?" below).

This new option will not change any existing behavior if it's not set. Next.js will prefer the Node.js Runtime for corresponding routes. This ensures the best ecosystem interoperability and support for self-hosting³.

2. Per-route Runtime Config

For each route (pages and API routes), you can export an option runtime config such as:

// Can be a page component, or an API route:
// pages/about.js, pages/api/user.js

export default function Page () { ... }

export const config = {
  runtime?: 'nodejs' | 'edge'
}

Note: this option must be static, so you can’t do things like export const config = { runtime: 'node' + 'js' }.

Same as the global runtime option, the per-route runtime is optional, and can be set to nodejs or edge as well. This option determines the runtime for this specific route, that will be used by SSR (gSSP-based SSR, Suspense-based SSR), SSG and API routes.

For a page route, if the runtime option is not set and there is no gSSP/gSP/gIP used, Next.js will do the automatic static optimization and there will be no server runtime involved.

The detailed behavior is listed below.

What’s happening under the hood?

If a third-party library uses Suspense for data fetching on the server it must only use static data. Otherwise it should throw an error on the server which triggers client rendering of that Suspense boundary instead. That's because if you use Suspense on the server, there's no way to get the correct snapshot of the data to the client for hydration. Therefore third-party Suspense libraries must only be used on the client, use static data or be client-only. Therefore Next.js will assume that it's safe to do Automatic Static Optimization.

This table lists the target runtime of different pages, when configuring with different per-route runtime option:

Route runtime Config	Page without gSSP, gSP, gIP	gSP	gSSP	gIP
runtime: 'edge'	Edge Runtime (SSG)	Edge Runtime (SSG)	Edge Runtime (SSR)	ERROR
runtime: 'nodejs'	Node.js Runtime (SSG)	Node.js Runtime (SSG)	Node.js Runtime (SSR)	Node.js Runtime (SSR)
Not set	Static	Fallback to the global runtime config	Fallback to the global runtime config	Node.js Runtime (SSR)

The global runtime config, when not specified, fallbacks to the Node.js Runtime. It prevents breaking changes from previous Next.js versions.

FAQ

What happens to my existing application, if Next.js ships this feature?

Nothing will happen and the behavior stays unchanged if you don't configure any of these new options. This new feature is backward compatible.

Can we automatically detect the best runtime for each page, instead of configuring it manually?

We are looking into this direction but it's not currently possible. Next.js needs to know the target runtime before compiling your code. And another reason is that we want to keep it deterministic for the user, and the runtime won’t change unexpectedly due to code and dependency changes.

For React 18, why doesn’t Next.js enable streaming SSR for every page by default?

This conflicts with Automatic Static Optimization of Next.js. If we do that, all pages will be SSR’d in-flight instead of served as static HTML files generated at build time (since we can’t simply tell if a page uses Suspense or not). This would be a breaking change for all existing applications (no matter you are self-hosting Next.js or deploying it to any hosting platform).

The runtime config serves like a hint to tell Next.js that this page has a SSR runtime.

I'm not using React 18 or React Server Components, why do I need this feature?

Even if React 18's new SSR architecture and Server Components are not used, you will still be able to customize the runtime for your gSSP and gSP functions as well as API routes.

I'm hosting Next.js in a Node.js server, can I use the Edge Runtime?

It will also be possible to use the Edge Runtime when self-hosting on a Node.js server. Using the Edge Runtime, even when self-hosted, provides isolation & simplicity benefits for deployment platforms like Kubernetes as well.

Footnotes

1. https://vercel.com/docs/concepts/functions/conceptual-model#cold-and-hot-boots ↩

2. https://github.com/reactwg/react-18/discussions/37 ↩

3. It will also be possible to use the Edge Runtime when self-hosting on a Node.js server. Using the Edge Runtime, even when self-hosted, provides security & simplicity benefits for deployment platforms like Kubernetes as well. ↩

[leo]

This is amazing, thank you!

After having switched over an application of mine to the new edge runtime (which required upgrading Next.js, of course), I noticed that the size of the bundles generated for edge SSR have increased in size dramatically, though: #34185.

This means that the "1 MB" threshold mentioned above has now been crossed:

	Node (server)	Node (lambda)	Edge
Cold Boot	/	~250ms	Instant
Code Size	/	50MB	1MB

[jescalan]

Hey Leo! Thanks so much for the detailed investigation and issue report here. Really appreciate this 🙏

We're still working out a lot of the edges on this one as it's on a canary release, but will make sure that this is resolved for sure before we go to stable!

[leo]

Awesome, thank you!

Seems like already decreased drastically in #34242.

[giovannibenussi]

This is going to be a great addition to Next.js! I have a few questions though.

Are you planning to run a real V8 or edge environment on development? This way errors are realistic if you try to use an unsupported API or any edge case that happens only in the production environment.

Also, the config export from pages is something new? I haven't seen it before. I'm not completely sure about this but setting experimental.runtime on next.config.js but runtime on the config export seems inconsistent because it's experimental in both cases. I'm ok with it if it makes the transition for the feature from experimental to stable easier for users.

[thescientist13]

Have been digging into Next and really liking it so far in the context of evaluating it for our business needs and the Middleware API is great! However, the limitations they impose as per the Edge Runtime restrictions... not so much. 😅

So it was great to see this Discussion in my searching as this limiting factor seems to come up often as a frequent topic when doing some casual searching of recent posts

• No access to server-side primitives in _middleware.ts? Alternatives? #33866
• Why not use Node.js Packages in MiddleWare？ #34790
• Can I run the new Next.js middleware in a self hosted environment? #30971
• Is there any reason why middleware is limited to specific web apis when not being used on edge functions? #34085

Presumably, with the option to specify the runtime as nodejs, the restrictions on access to NodeJS APIs would be lifted, and so one could use fs now? If so that would be great! 🌟

If not, is that something the team would consider and / or is there a way to turn "off" the Edge Runtime in the interim? Is that what something like next-connect is for?

Thanks!

[shuding]

Presumably, with the option to specify the runtime as nodejs, the restrictions on access to NodeJS APIs would be lifted, and so one could use fs now? If so that would be great! 🌟

Yes that's correct. When using nodejs as the runtime, you will be able to use all Node.js APIs such as fs.

[thescientist13]

awesome and thanks for the quick reply!

As an aside, was my assessment of next-connect correct at all in terms of it being an escape hatch of sorts, as an interim solution and work around? Or it is more like a shim / adapter to make using existing Express middleware in Next easier?

[Markos-Th09]

Is this coming soon?

[jescalan]

Yes it is! Currently being actively worked on 😁

[chris-schra]

any news on this?

[martinjlowm]

Looking forward to this! - I was a bit disappointed to learn the middleware is limited to the edge runtime at the moment.

We've developed our edge functions in Rust and are relying on loading dynamic modules using process.dlopen into the Node.js runtime. We use CloudFront + Lambda@Edge and hope that we can drop the Node.js runtime completely in the near future - but right now, for development, we depend on having process.dlopen exposed. In our existing setup, we've abused API routes to fulfill our needs. However, the middleware feature would simplify this quite a bit, and, what we essentially need at this point is an exposed nodejs runtime.

I hope this global runtime would apply to the development server as well, yes?

[Jelle-vz]

We ran into somewhat of the same issue(s). Any update on @martinjlowm 's question?

[enahsor]

Any updates on this? 🥹

[MDOR]

Any updates?

[jescalan]

Sorry for the slow response everyone -- yes, it's out as an experimental feature - docs can be seen here!

[MDOR]

@jescalan It is not working.

I tried:

// next.config.js
module.exports = {
  experimental: {
    runtime: 'nodejs',
  },
}

Also tried,

import { NextResponse } from 'next/server';
import { writeFile, readFile, appendFile } from 'fs/promises';

export async function middleware(req) { 
  appendFile(/* Do some stuff*/);
  return NextResponse.next();
}


export const config = {
  runtime: 'nodejs',
}

- nextjs: 12.2.3
- node: 18.3.0 

When printing the ENV variable, it is edge

[Jelle-vz]

As @martinjlowm mentioned here #34179 (reply in thread). The experimental flag does not apply to the runtime for middleware. Any feedback on that?

[MDOR]

Thanks for point that out, I lost that point. 👌🏼

[jugglingjsons]

@Jelle-vz Hey!
Are there any plans to support it for the middleware engine as well?
I would like to use httpCookie and proxy all requests through the Next.js backend, but all my attempts have failed for now.
I need to set custom headers on the request - which I want to set in the middleware (btw if there is a Next.js way to do it I am all ears, I've tried things like:

   return new NextResponse(null, {
    headers: {
      'x-middleware-rewrite': newURL,
      'customtoken': `${token}` // TODO: this doesn't seem to work currently
    }
  })

), maybe it's not the perfect approach , but I was really surprised when I could use neither:
'node-fetch', 'axios' or most other req, res libraries there because of the lack of support for both 'streams' and 'buffers'

[ItsWendell]

@shuding I've successfully tested the edge runtime to work with other V8-based (edge) providers like Cloudflare Pages / Workers, but I feel like the build output could be optimized to provide more flexibility and efficiency on where you deploy Next.js on the edge.

In the current implementation of the build export of Next.js, each function is implemented as its own individual server with only the routes for that one specific page or API endpoint. On platforms like Cloudflare, they require you to bundle everything into one single Worker. This means for it to run properly there, you'd need to write your own, custom router.

These individual functions also cause side-effects, currently in enhanceGlobals, which adds __import_unsupported to the global scope. A second SSR page definition in your bundle will crash the function since it can only be defined once:

next.js/packages/next/server/web/adapter.ts

Line 217 in 4cd8b23

export function enhanceGlobals() {

In an experimental implementation of an edge function that bundles these, I essentially import all the edge functions into a single one based on middleware-manifest.json. The imports luckily add an entry to the _ENTRIES global scope, which in turn we can use to forward requests within our custom router implementation.

Preferably, I'd love to see these pages exported more efficiently, maybe as truly individual pages with a separate file for the router/server, so that other tools and platforms can provide their own routers for it.

The Vercel Build API has this issue too, but worse since the Vercel Build Output API doesn't do chunking.

Would love to get your thoughts on supporting other platforms and what good methods forward would be.

Here's an example implementation https://nextflare-demo.pages.dev/ (source code is available on request).

[shuding]

The individual server bundling was an incremental path to implement this new runtime, over time it will become a lean wrapper on top of the actual component renderer. Then another bundle pass can combine these endpoints and add a router layer there. Another reason is to make it really lightweight and performant (size limitation and cold boot speed, differs on different platforms), so it's not ideal to concat all endpoints by default.

[ItsWendell]

The individual server bundling was an incremental path to implement this new runtime, over time it will become a lean wrapper on top of the actual component renderer. Then another bundle pass can combine these endpoints and add a router layer there. Another reason is to make it really lightweight and performant (size limitation and cold boot speed, differs on different platforms), so it's not ideal to concat all endpoints by default.

Makes sense, curious to see where this goes!

Something similar like the custom server functionality but then for WinterCG compatible runtimes (which vercel is a part of) would be great, since each runtime / provider might have different ways to access environment variables / static assets / etc, then you can implement those yourself.

Let me know if you'd like to see / hear more of my findings.

[wiesson]

Does the edge runtime supports post requests? I checked the docs and could not find any information that they could not

[thescientist13]

Just wanted to share feedback on this as well, as along with quite a few others in this thread, may have been under a different impression of the outcome here?

• RFC: Switchable Next.js Runtime #34179 (reply in thread)
• RFC: Switchable Next.js Runtime #34179 (comment)
• RFC: Switchable Next.js Runtime #34179 (comment)

As I understand it, prior to this change, here was the current status of support for Node / Edge

	Pages	APIs	Middleware
Node	✅	✅	🚫
Edge	🚫	🚫	✅

Now after this change, we have this

	Pages	APIs	Middleware
Node	✅	✅	🚫
Edge	✅	✅	✅

And so I think what might have caught myself and others by surprise is that Middleware + Node is still 🚫 ? Are we missing something? All of my testing has concluded that Middleware in NodeJS is not supported. 😢

So would it be possible to get Middleware in Node.js at some point? 💯

	Pages	APIs	Middleware
Node	✅	✅	✅
Edge	✅	✅	✅

[Brenndoerfer]

Looks like Middleware still does not support runtime: nodejs (next: 13.1.1)

Any plans to add this?

[mlagergren]

We're looking to implement authentication in some routes, and to me, it would make sense to do this in the middleware. As we're running this in Node it doesn't seem possible (our 3rd party library makes use of Node functionality).

+1 to have Middleware support in the runtime and some indications if that is in the plans would be awesome.

[jpkempf]

+1 for this, not being able to use a full Node runtime in middleware blocks some legitimate use cases. Not being able to use Buffer.from for instance limits the ability to decode JSON Web Tokens, which I'd like to be able to do for various reasons. My workaround for now is to use new Buffer, which is deprecated and won't be a viable solution forever. I may need to start offloading Node-dependent logic into API routes, which adds more complexity and unnecessary network requests.

Extending what the Edge runtime supports is probably counter to the reasons it was created in the first place, so being able to opt into forgoing the performance advantages and using Node instead would be nice to have.

Edit: I've realized that import { Buffer } from 'buffer' solves my particular issue. From what I read about Edge, I did not expect this to work. So my immediate pain is gone, but the general argument still stands.

[karlhorky]

Since this hasn't received a lot of attention here, I've created a new feature request discussion for improved visibility:

#46722

[thescientist13]

thank you @karlhorky ! 🙌

[arackaf]

Currently blocked even experimenting with Next 13 app directory until middleware can run as non-edge. What's especially frustrating is that this is self-hosted anyway. Our middleware is running in Node regardless!

Please let us remove this limitation 🙏🙏🙏

[pblanco-dekalabs]

I've lost a couple of hours researching too, because of this. Would love to see nodejs runtime in middlewares.

[oliverbenns]

Indeed, I would have liked to get a gcp secret, but it appears even that is unsupported due to the gcp client library using Node event apis not supported on edge. 😁

For self-hosters it does indeed make sense to allow those to use different runtimes, it feels like a bit of a Vercel lock-in at the moment. It would be great if we could solve this 🙂

[lukebrandonfarrell]

You can use https://nextjs.org/docs/messages/edge-dynamic-code-evaluation unstable_allowDynamic to solve this issue. Export the config from your middleware file.

[karlhorky]

@lukebrandonfarrell can you expand on how you suggest using this?

It seems like this flag is just about using eval(), new Function(), WebAssembly.compile and WebAssembly.instantiate.

It seems like it does not relate to usage of Node.js APIs, which is what @arackaf is asking for above (and also what #46722 is proposing)

[lukebrandonfarrell]

@karlhorky Of course, so yesterday I was experiencing an error when running next build:

info  - Creating an optimized production build  
Failed to compile.

./node_modules/graphql/error/GraphQLError.mjs
Dynamic Code Evaluation (e. g. 'eval', 'new Function', 'WebAssembly.compile') not allowed in Edge Runtime 
Learn More: https://nextjs.org/docs/messages/edge-dynamic-code-evaluation

Import trace for requested module:
./node_modules/graphql/error/GraphQLError.mjs
./node_modules/graphql/error/index.mjs
./node_modules/graphql/index.mjs
./node_modules/@apollo/client/core/LocalState.js
./node_modules/@apollo/client/core/ApolloClient.js
./node_modules/@apollo/client/core/index.js
./node_modules/@apollo/client/index.js
./src/utils/check-user-onboarding-status/check-user-onboarding-status.ts

This was due to creating a middleware in our application and using check-user-onboarding-status.ts (an internal util) which used @apollo, which uses graphql which apparently uses Dynamic Code Evaluation (e. g. 'eval', 'new Function', 'WebAssembly.compile').

Since we don't run on Vercel, but we run on AWS this wasn't a problem, so to bypass these build issues, we exported config from middleware:

export const config = {
  runtime: 'nodejs', // for Edge API Routes only
  unstable_allowDynamic: [
    '/src/utils/check-user-onboarding-status/check-user-onboarding-status.ts',
    '/node_modules/graphql/**',
  ],
};

Maybe this doesn't solve your specific issue, but I wanted to share what problem we were running into, how we can to this thread, and what solved it for us.

Hope that makes sense :)

[dima-kov]

Hey! Thank you all for great job!

I tried to use edge runtime on vercel with next 12.3.4 and it works wonderfully. I want to use runtime for all pages, so I turned on it with next.config.js:

const nextConfig = {
  ...
  experimental: {
    runtime: 'experimental-edge',
  },
  ...

but after upgrading to next 13.4.15, I does not work. I tried to delete runtime from experimental:

const nextConfig = {
  ...
  runtime: 'edge',
  ...

but it also does not work. Please help me to use edge runtime for the whole project

[emmgfx]

Is this RFC dead? No node runtime on middleware at all?

[goggle555]

I need a way to set the edge runtime to the whole project. Pages can be configured from a root layout, but API routes must be configured individually.

[andresgutgon]

I see this doc now
https://nextjs.org/docs/app/building-your-application/routing/middleware#runtime

I guess middleware can not be used with nodejs runtime.

[emmgfx]

I see this doc now
https://nextjs.org/docs/app/building-your-application/routing/middleware#runtime

I guess middleware can be used with nodejs runtime.

What do you mean? I clearly see:

Middleware currently only supports the Edge runtime. The Node.js runtime can not be used.

[andresgutgon]

Sorry I expressed very badly. I meant we can not use nodejs as runtime in middleware

[karlhorky]

Right, the Node.js runtime cannot be used with Middleware yet, I opened another discussion here for that:

• Switchable Runtime for Middleware (Allow Node.js APIs in Middleware) #46722

[paulschuetz]

Imagine building a framework for building web apps with server side rendering that does not support running simple functions on every http request on the server (to handle cross cutting concerns like logging, tracing, auth, cookies, headers). This restriction that middleware only runs in the edge runtime is awful. I spend a lot of time configuring middleware to work with my auth logic just to find out that I can not use it with my simple node.js custom deployment. I dont want to be forced to ANY hosting provider, I want to choose myself where I want to host the server that runs my app. This is the problem with a profit-oriented company really locking the community to a particular deployment platform. AT LEAST stating that middleware can only run in edge runtime which is only really supported by vercel should be the first thing in the middleware documentation, so everybody knows what they sign up for. Middleware running in node.js alongside the other server code should be the default and running on the edge should be the opt-in. Not the other way around! And the other way is not even supported... Man I had a bad gut feeling with next. How this got 100k stars? Delusional.

For all folks struggling with this and don't have the biggest performance requirements: Spin up a reverse proxy that handles your middleware stuff and route it to your actual pure node.js next.js server. And for folks who are not yet locked in: Really think about using something different than next :)

[Makakusnik]

Agreed, disgusting and sad.