How to enable React Compiler for React 18 Page Router Application?

[BruceHubbard]

Summary

I'm on [email protected] and I followed the instructions on this page: https://nextjs.org/docs/app/api-reference/config/next-config-js/reactCompiler by adding reactCompiler: true to my next.config.mjs. When I run our app I get:

Module not found: Package path ./compiler-runtime is not exported from package /Users/bruce/code/my_app/node_modules/react

When I search for a solution to that error I see this page on React's docs about making React Compiler targeting React 18 instead of 19 (which is the default): https://react.dev/reference/react-compiler/target. Do we need to follow these instructions as well?

Those instructions have us install npm install react-compiler-runtime@latest and then you have to pass a target flag to React Compiler. How do we do that within Next.js? It looks like from Next's React Compiler's docs we don't manually set up the babel-plugin-react-compiler manually, I'm guessing that Next.js does that for us? How then do we set the React version target?

Additional information

No response

Example

No response

[timkindberg]

I'd love to hear an answer to this as well.

[timkindberg]

Actually I think you can just pass options straight to the reactCompiler property in the next config:

https://github.com/vercel/next.js/blob/969f61f84761bf97ae0e86166161e8867917476f/packages/next/src/build/get-babel-loader-config.ts#L28C3-L33C4

[icyJoseph]

Try something like:

Install: react-compiler-runtime, and then for Turbopack for example:

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* config options here */
  reactStrictMode: true,
  turbopack: {
    resolveAlias: {
      'react/compiler-runtime': 'react-compiler-runtime'
    }
  },
  reactCompiler: true
};

export default nextConfig;

The dw component is the optimized devOverlay. The App component shows ✨ , which means it got passed through the React compiler.

[Arjun-M]

Hey @BruceHubbard , solid question—React Compiler's React 18 setup trips folks up since it defaults to 19 mode.

Quick fix:

1. Install the runtime: npm install react-compiler-runtime@latest

2. Update next.config.mjs like this (options pass straight to the Babel plugin):

   /** @type {import('next').NextConfig} */
   const nextConfig = {
     reactCompiler: {
       target: '18',
       runtimeModule: 'react-compiler-runtime',
     },
     // your other stuff
   };
   
   export default nextConfig;

3. Grab the plugin if missing: npm install -D babel-plugin-react-compiler@latest

4. Restart dev server. That should kill the import error. Works for Pages Router too (docs lag a bit).

If Turbopack's in play and it still flakes, add the alias @icyJoseph shared.

[BruceHubbard]

@Arjun-M Thanks, this worked for me! I also don't have Turbopack working yet so I couldn't try @icyJoseph's approach. I did have to rm -rf .next to allow it to rebuild after changing those settings but it seems to be pulling up the site now.

[icyJoseph]

I think this one would work too under Turbopack. The thing is that, the type for ReactCompilerOptions is very narrow, and doesn't define any of these.

• https://github.com/vercel/next.js/blob/canary/packages/next/src/server/config-shared.ts#L222

So, yeah, it is the contract that is at play here. If you do use next.config.ts you''l have to silence type errors.

With my fix, you can get around that, even in Webpack, just do:

  reactCompiler: true,
  webpack: (config) => {
    config.resolve.alias['react/compiler-runtime'] = require.resolve('react-compiler-runtime')
    return config
  }

[Arjun-M]

@BruceHubbard awesome, glad it clicked! ✅

yeah the .next cache wipe is basically mandatory the first time you flip the compiler on – it’s a one-time pain.

@icyJoseph love the webpack/turbopack alias tip too, that’s cleaner than the target hack for a lot of setups. gonna steal that one next time i’m on turbopack 😄

happy compiling dudes! 🚀