How to disable React in Next.js (unstable_runtimeJS)

Published: February 18, 2023

You can disable React from loading on your Next.js project by adding this piece of code inside your page template file or page file.

export const config = {
  unstable_runtimeJS: false
};

That's Next.js' native way of disabling React, in other words, runtime JavaScript.

Put it at the top level of the code, meaning that it is not inside a function, and instead is at the same level as the functions.

Here's one quick example of a page that will not have React:

import Layout from '../layout'

export const config = {
    unstable_runtimeJS: false
};

export default function ExamplePage() {
    return (
        <Layout>
            <h1>Hello world</h1>
        </Layout>
    )
}

React will still be loaded on the development environment, you need to do a production build of the site to see React not getting loaded.

Do note that this is an experimental setting, it's not exactly how Next.js is meant to be used. But that being said, I have used this on an actual production site, and I haven't had any problems with it.

Why did I use it? The site had almost no interactivity at all, but is large in size. Almost 900 pages. However, the visitor is not expected to visit more than one page, and since the site has almost no interactivity, it makes React an overkill for the website. Why waste so much visitor's processing power on running React's hydration, when it is not used at all? That's why I removed React from that Next.js site, making it pretty much free of JavaScript.

How to add JavaScript after removing React

Even after disabling React, you can of course still add JavaScript to the site. How? Well, using the good old <script> element of course!

Here's one example of using it:

<script dangerouslySetInnerHTML={{__html: `console.log('Hello world!')` }} />

Does that look a bit too.. dangerous? No, it doesn't! That's thanks to no React hydration being present on the page, the dangerouslySetInnerHTML gets executed only on build time, not on client side, as there is no React being used on the site. No danger here!

If you don't like having to use regular script tags just like, ugh, a non-React developer, then just use React! I'm just joking with the non-React developer part there, but really though, having React be part of the site is not an end of the world, plenty of Next.js sites are very performant and have React. Just use whatever you find the best!