Allow passing more options in `reactCompiler`

[dimaMachina]

Link to the code that reproduces this issue

inkeep/agents#3016

To Reproduce

try to set validateNoImpureFunctionsInRender: true in next.config

Current vs. Expected behavior

Currently it's possible to configure only compilationMode and panicThreshold options in reactCompiler, I wasn't able to turn in validateNoImpureFunctionsInRender which is turn in in React compiler playground

Provide environment information

Operating System:
  Platform: darwin
  Arch: x64
  Version: Darwin Kernel Version 24.2.0: Fri Dec  6 18:56:34 PST 2024; root:xnu-11215.61.5~2/RELEASE_ARM64_T6020
  Available memory (MB): 98304
  Available CPU cores: 12
Binaries:
  Node: 22.21.1
  npm: 10.9.4
  Yarn: N/A
  pnpm: 10.33.0
Relevant Packages:
  next: 16.2.2 // Latest available version is detected (16.2.2).
  eslint-config-next: N/A
  react: 19.2.4
  react-dom: 19.2.4
  typescript: N/A
Next.js Config:
  output: standalone

Which area(s) are affected? (Select all that apply)

React

Which stage(s) are affected? (Select all that apply)

next build (local)

Additional context

No response

[bgw]

This isn't documented as a configuration flag in React Compiler? https://react.dev/reference/react-compiler/configuration

The playground exposes many internal details and possibly some incomplete features of the compiler.

Values in environment are apparently not supposed to be directly passed into the Babel config: https://github.com/facebook/react/blob/1b45e2439289fd8e094c44161c89e06c5488671e/compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Options.ts#L341

It looks like this is handled as a prama comment: https://github.com/search?q=repo%3Afacebook%2Freact%20validateNoImpureFunctionsInRender&type=code

Try adding

// @validateNoImpureFunctionsInRender

to the top of the files where you want this check applied.

If this becomes an option that can be set in the React Compiler configuration object passed to Babel, then we could add the option to the next.config.js file, but that does not currently appear to be the case.

[dimaMachina]

It looks like this is handled as a prama comment:

The option is being passed using environment.validateNoImpureFunctionsInRender: true

to the top of the files where you want this check applied.

This approach isn’t scalable. I’d like to apply this option globally, similar to how configuration of bable plugin options works in tools like Vite or Babel

If this becomes an option that can be set in the React Compiler configuration object passed to Babel, then we could add the option to the next.config.js file, but that does not currently appear to be the case.

this is already supported as an option.

https://playground.react.dev/#N4Igzg9grgTgxgUxALhAgHgBwjALgAgBMEAzAQygBsCSoA7OXASwjvwFkBPAYQgFtsdBHVwAKAJT5gAHTb4YCXLDYAeAHzB2ZXAAsAdDDJ1C-CQF8VAejWyzIADQg4rEkwDmKEDLnS0dAG5MMKx8wri+yFKy+DH4vv5klEyE2ggAchAAkgKwCABi9IwsdGCZdABKwsQwEfi4MFAI0fhmtg7gOhAA7mW4CDB0iWAo5JRgCGZAA

[dimaMachina]

friendly ping @bgw

[bgw]

@dimaMachina I've been asking around internally, but because this feature is undocumented, it seems like it may not be stable or intentionally exposed. If I hear anything otherwise from a React Compiler maintainer or if the documentation is updated to include these environment options, I'm happy to switch positions.

I also can't find anyone actually using this feature in a serious way, aside from react.dev, which might just be dogfooding experimental features.

In react.dev, they only use the option in their eslint config, they don't run this validation during normal compilation. That might be a better example for you to follow, as running additional checks during compilation will likely slow down your build. https://github.com/reactjs/react.dev/blob/abe931a8cb3aee3e8b15ef7e187214789164162a/eslint-local-rules/rules/react-compiler.js#L24

[dimaMachina]

I've been asking around internally, but because this feature is undocumented, it seems like it may not be stable or intentionally exposed. If I hear anything otherwise from a React Compiler maintainer or if the documentation is updated to include these environment options, I'm happy to switch positions.

this option is not documented in react website, but all options are documented via JSDoc comments

https://github.com/facebook/react/blob/94643c3b8516928e4cc7fad99912272670a0a990/compiler/packages/babel-plugin-react-compiler/src/HIR/Environment.ts#L142-L505

and in README.md

https://github.com/facebook/react/blob/94643c3b8516928e4cc7fad99912272670a0a990/compiler/packages/babel-plugin-react-compiler/docs/passes/README.md?plain=1#L269-L278

We are already using several of these options, e.g.:

• validateNoDerivedComputationsInEffects
• validateNoImpureFunctionsInRender
• enableJsxOutlining

That might be a better example for you to follow, as running additional checks during compilation will likely slow down your build.

We're not concerned about slower builds. Our priority is enabling additional validation and optimization features like enableJsxOutlining.

If these options are configurable via babel-plugin-react-compiler, they should be exposed to end users, similar to how tools like Vite allow configuration them. cc @bgw

[bgw]

@dimaMachina both of those links look like internal documentation.

@eps1lon thinks that these are internals that are simply exposed for the eslint plugin to use. I tend to agree.

We're not concerned about slower builds. Our priority is enabling additional validation and optimization features like enableJsxOutlining.

Run eslint with the react compiler plugin alongside your build. Linting and building are separable concerns.

If these options are configurable via babel-plugin-react-compiler, they should be exposed to end users, similar to how tools like Vite allow configuration them.

• If they're unintentionally exposed and/or not a stable API, then we should not expose them to end users. I don't know what is or isn't intentional or stable unless the public docs say it clearly or somebody from the react compiler team comments otherwise.
• Your code patches babel-plugin-react-compiler, so I'm not even sure it is possible to pass these options in normally.
• I can't find good examples of anybody using these options outside of with eslint.

[dimaMachina]

@eps1lon thinks that these are internals that are simply exposed for the eslint plugin to use. I tend to agree.

environment.validate* options maybe, but not environment.enable* options which affect compilation behavior. See environment.enableJsxOutlining, and check JSDoc example to see how code will be transformed differently with this option.

Your code patches babel-plugin-react-compiler

I patch babel-plugin-react-compiler because there is currently no way to pass these options through Next.js, and I opened this issue because I want to remove that patch.

so I'm not even sure it is possible to pass these options in normally.

You just showed an example of how these options are passed 👇

In react.dev, they only use the option in their eslint config, they don't run this validation during normal compilation. That might be a better example for you to follow, as running additional checks during compilation will likely slow down your build. https://github.com/reactjs/react.dev/blob/abe931a8cb3aee3e8b15ef7e187214789164162a/eslint-local-rules/rules/react-compiler.js#L24

environment is passed correctly in Vite, just like gating or logger which also cannot currently be configured in Next.js.

---

The current babel-plugin-react-compiler integration in Next.js is only partial. Either allow users to configure whatever they need in babel-plugin-react-compiler, or provide a valid example of how to integrate babel-plugin-react-compiler without relying on the nextConfig.reactCompiler option.

[github-actions]

This closed issue has been automatically locked because it had no new activity for 2 weeks. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.