Skip to content

Commit 5f9a481

Browse files
potetopoteto
committed
[compiler] Rewrite React Compiler Docs
We've received feedback that the compiler docs are difficult to understand and not prominent enough that people don't realize the compiler is a serious project and is near stable. This PR rewrites the whole compiler doc section, giving it its own category as well as a standalone reference page.
1 parent 84a5696 commit 5f9a481

15 files changed

+1317
-349
lines changed

‎src/content/learn/react-compiler.md

Lines changed: 0 additions & 346 deletions
This file was deleted.

‎src/content/learn/react-compiler/compatibility.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: Backwards Compatibility
3+
---
4+
5+
<Intro>
6+
React Compiler works best with React 19, but it also supports React 17 and 18 with additional configuration.
7+
</Intro>
8+
9+
<YouWillLearn>
10+
11+
* How to configure React Compiler for React 17 and 18
12+
13+
</YouWillLearn>
14+
15+
## Using React Compiler with React 17 or 18 {/*using-react-compiler-with-react-17-or-18*/}
16+
17+
React Compiler does not require any special configuration to work with React 19. For React 17 or 18, you need two things:
18+
19+
### 1. Install the runtime package {/*install-runtime-package*/}
20+
21+
<TerminalBlock>
22+
npm install react-compiler-runtime@rc
23+
</TerminalBlock>
24+
25+
### 2. Configure the target version {/*configure-target-version*/}
26+
27+
```js {5}
28+
// babel.config.js
29+
module.exports = {
30+
plugins: [
31+
['babel-plugin-react-compiler', {
32+
target: '18', // or '17' for React 17
33+
}],
34+
],
35+
};
36+
```
37+
38+
Always use the major version number as a string for the `target` option. Use `'17'` not `17` or `'17.0.2'`.
39+
40+
## Framework-specific configuration {/*framework-specific-configuration*/}
41+
42+
### Next.js {/*nextjs*/}
43+
44+
```js {5}
45+
// next.config.js
46+
module.exports = {
47+
experimental: {
48+
reactCompiler: {
49+
target: '18',
50+
},
51+
},
52+
};
53+
```
54+
55+
### Vite {/*vite*/}
56+
57+
```js {10}
58+
// vite.config.js
59+
import { defineConfig } from 'vite';
60+
import react from '@vitejs/plugin-react';
61+
62+
export default defineConfig({
63+
plugins: [
64+
react({
65+
babel: {
66+
plugins: [
67+
['babel-plugin-react-compiler', { target: '17' }],
68+
],
69+
},
70+
}),
71+
],
72+
});
73+
```
74+

‎src/content/learn/react-compiler/configuration.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: Configuration
3+
---
4+
5+
<Intro>
6+
React Compiler is designed to work out of the box with no configuration needed. Most users will not need to configure the compiler. However, if you need to customize its behavior, various configuration options are available.
7+
</Intro>
8+
9+
<YouWillLearn>
10+
11+
* Available configuration options
12+
* How to configure the compiler
13+
14+
</YouWillLearn>
15+
16+
## Configuration Options Overview {/*configuration-options-overview*/}
17+
18+
React Compiler accepts several options to customize its behavior. See the [API reference](/reference/react/react-compiler) for detailed documentation of each option.
19+
20+
- **`compilationMode`** - Controls which functions to compile
21+
- **`target`** - Specifies the React version for compatibility (17, 18, or 19)
22+
- **`sources`** - Limits compilation to specific files or directories
23+
- **`gating`** - Enables runtime feature flags for [incremental adoption](/learn/react-compiler/incremental-adoption)
24+
- **`logger`** - Configures logging output for debugging
25+
- **`panicThreshold`** - Sets when the compiler should halt on errors
26+
- **`noEmit`** - Disables code generation
27+
28+
## Basic Configuration {/*basic-configuration*/}
29+
30+
Pass options to the Babel plugin:
31+
32+
```js
33+
// babel.config.js
34+
module.exports = {
35+
plugins: [
36+
['babel-plugin-react-compiler', {
37+
target: '18', // For React 18 compatibility
38+
}],
39+
],
40+
};
41+
```
42+
43+
## Framework Examples {/*framework-examples*/}
44+
45+
### Next.js {/*nextjs*/}
46+
47+
```js
48+
// next.config.js
49+
module.exports = {
50+
experimental: {
51+
reactCompiler: {
52+
target: '18',
53+
},
54+
},
55+
};
56+
```
57+
58+
### Vite {/*vite*/}
59+
60+
```js
61+
// vite.config.js
62+
export default {
63+
plugins: [
64+
react({
65+
babel: {
66+
plugins: [
67+
['babel-plugin-react-compiler', { /* options */ }],
68+
],
69+
},
70+
}),
71+
],
72+
};
73+
```
74+
75+
## Learn More {/*learn-more*/}
76+
77+
For detailed documentation of all configuration options, see the [React Compiler API reference](/reference/react/react-compiler).
78+
79+
For incremental adoption strategies using these options, see the [incremental adoption guide](/learn/react-compiler/incremental-adoption).

‎src/content/learn/react-compiler/debugging.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Debugging and Troubleshooting
3+
---
4+
5+
<Intro>
6+
This guide helps you identify and fix issues when using React Compiler. Learn how to debug compilation problems and resolve common issues.
7+
</Intro>
8+
9+
<YouWillLearn>
10+
11+
* The difference between compiler errors and runtime issues
12+
* Common patterns that break compilation
13+
* Step-by-step debugging workflow
14+
15+
</YouWillLearn>
16+
17+
## Understanding Compiler Behavior {/*understanding-compiler-behavior*/}
18+
19+
React Compiler is designed to handle code that follows the [Rules of React](/reference/rules). When it encounters code that might break these rules, it safely skips optimization rather than risk changing your app's behavior.
20+
21+
### Compiler Errors vs Runtime Issues {/*compiler-errors-vs-runtime-issues*/}
22+
23+
**Compiler errors** occur at build time and prevent your code from compiling. These are rare because the compiler is designed to skip problematic code rather than fail.
24+
25+
**Runtime issues** occur when compiled code behaves differently than expected. Most of the time, if you encounter an issue with React Compiler, it's a runtime issue. This typically happens when your code violates the Rules of React in subtle ways that the compiler couldn't detect, and the compiler mistakenly compiled a component it should have skipped.
26+
27+
When debugging runtime issues, focus your efforts on finding Rules of React violations in the affected components. The compiler relies on your code following these rules, and when they're broken in ways it can't detect, that's when runtime problems occur.
28+
29+
30+
## Common Breaking Patterns {/*common-breaking-patterns*/}
31+
32+
One of the main ways React Compiler can break your app is if your code was written to rely on memoization for correctness. This means your app depends on specific values being memoized to work properly. Since the compiler may memoize differently than your manual approach, this can lead to unexpected behavior like effects over-firing, infinite loops, or missing updates.
33+
34+
Common scenarios where this occurs:
35+
36+
- **Effects that rely on referential equality** - When effects depend on objects or arrays maintaining the same reference across renders
37+
- **Dependency arrays that need stable references** - When unstable dependencies cause effects to fire too often or create infinite loops
38+
- **Conditional logic based on reference checks** - When code uses referential equality checks for caching or optimization
39+
40+
## Debugging Workflow {/*debugging-workflow*/}
41+
42+
Follow these steps when you encounter issues:
43+
44+
### Compiler Build Errors {/*compiler-build-errors*/}
45+
46+
If you encounter a compiler error that unexpectedly breaks your build, this is likely a bug in the compiler. Report it to the [facebook/react](https://github.com/facebook/react/issues) repository with:
47+
- The error message
48+
- The code that caused the error
49+
- Your React and compiler versions
50+
51+
### Runtime Issues {/*runtime-issues*/}
52+
53+
For runtime behavior issues:
54+
55+
### 1. Temporarily Disable Compilation {/*temporarily-disable-compilation*/}
56+
57+
Use `"use no memo"` to isolate whether an issue is compiler-related:
58+
59+
```js
60+
function ProblematicComponent() {
61+
"use no memo"; // Skip compilation for this component
62+
// ... rest of component
63+
}
64+
```
65+
66+
If the issue disappears, it's likely related to a Rules of React violation.
67+
68+
You can also try removing manual memoization (useMemo, useCallback, memo) from the problematic component to verify that your app works correctly without any memoization. If the bug still occurs when all memoization is removed, you have a Rules of React violation that needs to be fixed.
69+
70+
### 2. Fix Issues Step by Step {/*fix-issues-step-by-step*/}
71+
72+
1. Identify the root cause (often memoization-for-correctness)
73+
2. Test after each fix
74+
3. Remove `"use no memo"` once fixed
75+
4. Verify the component shows the ✨ badge in React DevTools
76+
77+
## Reporting Compiler Bugs {/*reporting-compiler-bugs*/}
78+
79+
If you believe you've found a compiler bug:
80+
81+
1. **Verify it's not a Rules of React violation** - Check with ESLint
82+
2. **Create a minimal reproduction** - Isolate the issue in a small example
83+
3. **Test without the compiler** - Confirm the issue only occurs with compilation
84+
4. **File an [issue](https://github.com/facebook/react/issues/new?template=compiler_bug_report.yml)**:
85+
- React and compiler versions
86+
- Minimal reproduction code
87+
- Expected vs actual behavior
88+
- Any error messages
89+
90+
## Next Steps {/*next-steps*/}
91+
92+
- Review the [Rules of React](/reference/rules) to prevent issues
93+
- Check the [incremental adoption guide](/learn/react-compiler/incremental-adoption) for gradual rollout strategies

0 commit comments

Comments
 (0)