diff --git a/next-env.d.ts b/next-env.d.ts
index bc6d2a23de4..52e831b4342 100644
--- a/next-env.d.ts
+++ b/next-env.d.ts
@@ -1,10 +1,3 @@
-/**
- * Copyright (c) Meta Platforms, Inc. and affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
///
///
diff --git a/src/content/reference/eslint-plugin-react-hooks/index.md b/src/content/reference/eslint-plugin-react-hooks/index.md
new file mode 100644
index 00000000000..6494bd78f01
--- /dev/null
+++ b/src/content/reference/eslint-plugin-react-hooks/index.md
@@ -0,0 +1,37 @@
+---
+title: eslint-plugin-react-hooks
+---
+
+
+
+`eslint-plugin-react-hooks` provides ESLint rules to enforce the [Rules of React](/reference/rules).
+
+
+
+This plugin helps you catch violations of React's rules at build time, ensuring your components and hooks follow React's rules for correctness and performance. The lints cover both fundamental React patterns (exhaustive-deps and rules-of-hooks) and issues flagged by React Compiler. React Compiler diagnostics are automatically surfaced by this ESLint plugin, and can be used even if your app hasn't adopted the compiler yet.
+
+
+When the compiler reports a diagnostic, it means that the compiler was able to statically detect a pattern that is not supported or breaks the Rules of React. When it detects this, it **automatically** skips over those components and hooks, while keeping the rest of your app compiled. This ensures optimal coverage of safe optimizations that won't break your app.
+
+What this means for linting, is that you don’t need to fix all violations immediately. Address them at your own pace to gradually increase the number of optimized components.
+
+
+## Available Lints {/*available-lints*/}
+
+* [`component-hook-factories`](/reference/eslint-plugin-react-hooks/lints/component-hook-factories) - Validates against higher order functions defining nested components or hooks
+* [`config`](/reference/eslint-plugin-react-hooks/lints/config) - Validates the compiler configuration options
+* [`error-boundaries`](/reference/eslint-plugin-react-hooks/lints/error-boundaries) - Validates usage of Error Boundaries instead of try/catch for child errors
+* [`exhaustive-deps`](/reference/eslint-plugin-react-hooks/lints/exhaustive-deps) - Validates that dependency arrays for React hooks contain all necessary dependencies
+* [`gating`](/reference/eslint-plugin-react-hooks/lints/gating) - Validates configuration of gating mode
+* [`globals`](/reference/eslint-plugin-react-hooks/lints/globals) - Validates against assignment/mutation of globals during render
+* [`immutability`](/reference/eslint-plugin-react-hooks/lints/immutability) - Validates against mutating props, state, and other immutable values
+* [`incompatible-library`](/reference/eslint-plugin-react-hooks/lints/incompatible-library) - Validates against usage of libraries which are incompatible with memoization
+* [`preserve-manual-memoization`](/reference/eslint-plugin-react-hooks/lints/preserve-manual-memoization) - Validates that existing manual memoization is preserved by the compiler
+* [`purity`](/reference/eslint-plugin-react-hooks/lints/purity) - Validates that components/hooks are pure by checking known-impure functions
+* [`refs`](/reference/eslint-plugin-react-hooks/lints/refs) - Validates correct usage of refs, not reading/writing during render
+* [`rules-of-hooks`](/reference/eslint-plugin-react-hooks/lints/rules-of-hooks) - Validates that components and hooks follow the Rules of Hooks
+* [`set-state-in-effect`](/reference/eslint-plugin-react-hooks/lints/set-state-in-effect) - Validates against calling setState synchronously in an effect
+* [`set-state-in-render`](/reference/eslint-plugin-react-hooks/lints/set-state-in-render) - Validates against setting state during render
+* [`static-components`](/reference/eslint-plugin-react-hooks/lints/static-components) - Validates that components are static, not recreated every render
+* [`unsupported-syntax`](/reference/eslint-plugin-react-hooks/lints/unsupported-syntax) - Validates against syntax that React Compiler does not support
+* [`use-memo`](/reference/eslint-plugin-react-hooks/lints/use-memo) - Validates usage of the `useMemo` hook without a return value
\ No newline at end of file
diff --git a/src/content/reference/eslint-plugin-react-hooks/lints/component-hook-factories.md b/src/content/reference/eslint-plugin-react-hooks/lints/component-hook-factories.md
new file mode 100644
index 00000000000..537903abdd0
--- /dev/null
+++ b/src/content/reference/eslint-plugin-react-hooks/lints/component-hook-factories.md
@@ -0,0 +1,102 @@
+---
+title: component-hook-factories
+---
+
+
+
+Validates against higher order functions defining nested components or hooks. Components and hooks should be defined at the module level.
+
+
+
+## Rule Details {/*rule-details*/}
+
+Defining components or hooks inside other functions creates new instances on every call. React treats each as a completely different component, destroying and recreating the entire component tree, losing all state, and causing performance problems.
+
+### Invalid {/*invalid*/}
+
+Examples of incorrect code for this rule:
+
+```js {expectedErrors: {'react-compiler': [14]}}
+// ❌ Factory function creating components
+function createComponent(defaultValue) {
+ return function Component() {
+ // ...
+ };
+}
+
+// ❌ Component defined inside component
+function Parent() {
+ function Child() {
+ // ...
+ }
+
+ return ;
+}
+
+// ❌ Hook factory function
+function createCustomHook(endpoint) {
+ return function useData() {
+ // ...
+ };
+}
+```
+
+### Valid {/*valid*/}
+
+Examples of correct code for this rule:
+
+```js
+// ✅ Component defined at module level
+function Component({ defaultValue }) {
+ // ...
+}
+
+// ✅ Custom hook at module level
+function useData(endpoint) {
+ // ...
+}
+```
+
+## Troubleshooting {/*troubleshooting*/}
+
+### I need dynamic component behavior {/*dynamic-behavior*/}
+
+You might think you need a factory to create customized components:
+
+```js
+// ❌ Wrong: Factory pattern
+function makeButton(color) {
+ return function Button({children}) {
+ return (
+
+ );
+ };
+}
+
+const RedButton = makeButton('red');
+const BlueButton = makeButton('blue');
+```
+
+Pass [JSX as children](/learn/passing-props-to-a-component#passing-jsx-as-children) instead:
+
+```js
+// ✅ Better: Pass JSX as children
+function Button({color, children}) {
+ return (
+
+ );
+}
+
+function App() {
+ return (
+ <>
+
+
+
+ );
+}
+```
diff --git a/src/content/reference/eslint-plugin-react-hooks/lints/config.md b/src/content/reference/eslint-plugin-react-hooks/lints/config.md
new file mode 100644
index 00000000000..719e08412e5
--- /dev/null
+++ b/src/content/reference/eslint-plugin-react-hooks/lints/config.md
@@ -0,0 +1,90 @@
+---
+title: config
+---
+
+
+
+Validates the compiler [configuration options](/reference/react-compiler/configuration).
+
+
+
+## Rule Details {/*rule-details*/}
+
+React Compiler accepts various [configuration options](/reference/react-compiler/configuration) to control its behavior. This rule validates that your configuration uses correct option names and value types, preventing silent failures from typos or incorrect settings.
+
+### Invalid {/*invalid*/}
+
+Examples of incorrect code for this rule:
+
+```js
+// ❌ Unknown option name
+module.exports = {
+ plugins: [
+ ['babel-plugin-react-compiler', {
+ compileMode: 'all' // Typo: should be compilationMode
+ }]
+ ]
+};
+
+// ❌ Invalid option value
+module.exports = {
+ plugins: [
+ ['babel-plugin-react-compiler', {
+ compilationMode: 'everything' // Invalid: use 'all' or 'infer'
+ }]
+ ]
+};
+```
+
+### Valid {/*valid*/}
+
+Examples of correct code for this rule:
+
+```js
+// ✅ Valid compiler configuration
+module.exports = {
+ plugins: [
+ ['babel-plugin-react-compiler', {
+ compilationMode: 'infer',
+ panicThreshold: 'critical_errors'
+ }]
+ ]
+};
+```
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Configuration not working as expected {/*config-not-working*/}
+
+Your compiler configuration might have typos or incorrect values:
+
+```js
+// ❌ Wrong: Common configuration mistakes
+module.exports = {
+ plugins: [
+ ['babel-plugin-react-compiler', {
+ // Typo in option name
+ compilationMod: 'all',
+ // Wrong value type
+ panicThreshold: true,
+ // Unknown option
+ optimizationLevel: 'max'
+ }]
+ ]
+};
+```
+
+Check the [configuration documentation](/reference/react-compiler/configuration) for valid options:
+
+```js
+// ✅ Better: Valid configuration
+module.exports = {
+ plugins: [
+ ['babel-plugin-react-compiler', {
+ compilationMode: 'all', // or 'infer'
+ panicThreshold: 'none', // or 'critical_errors', 'all_errors'
+ // Only use documented options
+ }]
+ ]
+};
+```
diff --git a/src/content/reference/eslint-plugin-react-hooks/lints/error-boundaries.md b/src/content/reference/eslint-plugin-react-hooks/lints/error-boundaries.md
new file mode 100644
index 00000000000..830098e5be3
--- /dev/null
+++ b/src/content/reference/eslint-plugin-react-hooks/lints/error-boundaries.md
@@ -0,0 +1,72 @@
+---
+title: error-boundaries
+---
+
+
+
+Validates usage of Error Boundaries instead of try/catch for errors in child components.
+
+
+
+## Rule Details {/*rule-details*/}
+
+Try/catch blocks can't catch errors that happen during React's rendering process. Errors thrown in rendering methods or hooks bubble up through the component tree. Only [Error Boundaries](/reference/react/Component#catching-rendering-errors-with-an-error-boundary) can catch these errors.
+
+### Invalid {/*invalid*/}
+
+Examples of incorrect code for this rule:
+
+```js {expectedErrors: {'react-compiler': [4]}}
+// ❌ Try/catch won't catch render errors
+function Parent() {
+ try {
+ return ; // If this throws, catch won't help
+ } catch (error) {
+ return
Error occurred
;
+ }
+}
+```
+
+### Valid {/*valid*/}
+
+Examples of correct code for this rule:
+
+```js
+// ✅ Using error boundary
+function Parent() {
+ return (
+
+
+
+ );
+}
+```
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Why is the linter telling me not to wrap `use` in `try`/`catch`? {/*why-is-the-linter-telling-me-not-to-wrap-use-in-trycatch*/}
+
+The `use` hook doesn't throw errors in the traditional sense, it suspends component execution. When `use` encounters a pending promise, it suspends the component and lets React show a fallback. Only Suspense and Error Boundaries can handle these cases. The linter warns against `try`/`catch` around `use` to prevent confusion as the `catch` block would never run.
+
+```js {expectedErrors: {'react-compiler': [5]}}
+// ❌ Try/catch around `use` hook
+function Component({promise}) {
+ try {
+ const data = use(promise); // Won't catch - `use` suspends, not throws
+ return
{data}
;
+ } catch (error) {
+ return
Failed to load
; // Unreachable
+ }
+}
+
+// ✅ Error boundary catches `use` errors
+function App() {
+ return (
+ Failed to load}>
+ Loading...}>
+
+
+
+ );
+}
+```
\ No newline at end of file
diff --git a/src/content/reference/eslint-plugin-react-hooks/lints/exhaustive-deps.md b/src/content/reference/eslint-plugin-react-hooks/lints/exhaustive-deps.md
new file mode 100644
index 00000000000..cd26483a14b
--- /dev/null
+++ b/src/content/reference/eslint-plugin-react-hooks/lints/exhaustive-deps.md
@@ -0,0 +1,155 @@
+---
+title: exhaustive-deps
+---
+
+
+
+Validates that dependency arrays for React hooks contain all necessary dependencies.
+
+
+
+## Rule Details {/*rule-details*/}
+
+React hooks like `useEffect`, `useMemo`, and `useCallback` accept dependency arrays. When a value referenced inside these hooks isn't included in the dependency array, React won't re-run the effect or recalculate the value when that dependency changes. This causes stale closures where the hook uses outdated values.
+
+## Common Violations {/*common-violations*/}
+
+This error often happens when you try to "trick" React about dependencies to control when an effect runs. Effects should synchronize your component with external systems. The dependency array tells React which values the effect uses, so React knows when to re-synchronize.
+
+If you find yourself fighting with the linter, you likely need to restructure your code. See [Removing Effect Dependencies](/learn/removing-effect-dependencies) to learn how.
+
+### Invalid {/*invalid*/}
+
+Examples of incorrect code for this rule:
+
+```js
+// ❌ Missing dependency
+useEffect(() => {
+ console.log(count);
+}, []); // Missing 'count'
+
+// ❌ Missing prop
+useEffect(() => {
+ fetchUser(userId);
+}, []); // Missing 'userId'
+
+// ❌ Incomplete dependencies
+useMemo(() => {
+ return items.sort(sortOrder);
+}, [items]); // Missing 'sortOrder'
+```
+
+### Valid {/*valid*/}
+
+Examples of correct code for this rule:
+
+```js
+// ✅ All dependencies included
+useEffect(() => {
+ console.log(count);
+}, [count]);
+
+// ✅ All dependencies included
+useEffect(() => {
+ fetchUser(userId);
+}, [userId]);
+```
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Adding a function dependency causes infinite loops {/*function-dependency-loops*/}
+
+You have an effect, but you're creating a new function on every render:
+
+```js
+// ❌ Causes infinite loop
+const logItems = () => {
+ console.log(items);
+};
+
+useEffect(() => {
+ logItems();
+}, [logItems]); // Infinite loop!
+```
+
+In most cases, you don't need the effect. Call the function where the action happens instead:
+
+```js
+// ✅ Call it from the event handler
+const logItems = () => {
+ console.log(items);
+};
+
+return ;
+
+// ✅ Or derive during render if there's no side effect
+items.forEach(item => {
+ console.log(item);
+});
+```
+
+If you genuinely need the effect (for example, to subscribe to something external), make the dependency stable:
+
+```js
+// ✅ useCallback keeps the function reference stable
+const logItems = useCallback(() => {
+ console.log(items);
+}, [items]);
+
+useEffect(() => {
+ logItems();
+}, [logItems]);
+
+// ✅ Or move the logic straight into the effect
+useEffect(() => {
+ console.log(items);
+}, [items]);
+```
+
+### Running an effect only once {/*effect-on-mount*/}
+
+You want to run an effect once on mount, but the linter complains about missing dependencies:
+
+```js
+// ❌ Missing dependency
+useEffect(() => {
+ sendAnalytics(userId);
+}, []); // Missing 'userId'
+```
+
+Either include the dependency (recommended) or use a ref if you truly need to run once:
+
+```js
+// ✅ Include dependency
+useEffect(() => {
+ sendAnalytics(userId);
+}, [userId]);
+
+// ✅ Or use a ref guard inside an effect
+const sent = useRef(false);
+
+useEffect(() => {
+ if (sent.current) {
+ return;
+ }
+
+ sent.current = true;
+ sendAnalytics(userId);
+}, [userId]);
+```
+
+## Options {/*options*/}
+
+This rule accepts an options object:
+
+```js
+{
+ "rules": {
+ "react-hooks/exhaustive-deps": ["warn", {
+ "additionalHooks": "(useMyCustomHook|useAnotherHook)"
+ }]
+ }
+}
+```
+
+- `additionalHooks`: Regex for hooks that should be checked for exhaustive dependencies
diff --git a/src/content/reference/eslint-plugin-react-hooks/lints/gating.md b/src/content/reference/eslint-plugin-react-hooks/lints/gating.md
new file mode 100644
index 00000000000..3bd662a86e1
--- /dev/null
+++ b/src/content/reference/eslint-plugin-react-hooks/lints/gating.md
@@ -0,0 +1,72 @@
+---
+title: gating
+---
+
+
+
+Validates configuration of [gating mode](/reference/react-compiler/gating).
+
+
+
+## Rule Details {/*rule-details*/}
+
+Gating mode lets you gradually adopt React Compiler by marking specific components for optimization. This rule ensures your gating configuration is valid so the compiler knows which components to process.
+
+### Invalid {/*invalid*/}
+
+Examples of incorrect code for this rule:
+
+```js
+// ❌ Missing required fields
+module.exports = {
+ plugins: [
+ ['babel-plugin-react-compiler', {
+ gating: {
+ importSpecifierName: '__experimental_useCompiler'
+ // Missing 'source' field
+ }
+ }]
+ ]
+};
+
+// ❌ Invalid gating type
+module.exports = {
+ plugins: [
+ ['babel-plugin-react-compiler', {
+ gating: '__experimental_useCompiler' // Should be object
+ }]
+ ]
+};
+```
+
+### Valid {/*valid*/}
+
+Examples of correct code for this rule:
+
+```js
+// ✅ Complete gating configuration
+module.exports = {
+ plugins: [
+ ['babel-plugin-react-compiler', {
+ gating: {
+ importSpecifierName: 'isCompilerEnabled', // exported function name
+ source: 'featureFlags' // module name
+ }
+ }]
+ ]
+};
+
+// featureFlags.js
+export function isCompilerEnabled() {
+ // ...
+}
+
+// ✅ No gating (compile everything)
+module.exports = {
+ plugins: [
+ ['babel-plugin-react-compiler', {
+ // No gating field - compiles all components
+ }]
+ ]
+};
+```
diff --git a/src/content/reference/eslint-plugin-react-hooks/lints/globals.md b/src/content/reference/eslint-plugin-react-hooks/lints/globals.md
new file mode 100644
index 00000000000..fe0cbe0080f
--- /dev/null
+++ b/src/content/reference/eslint-plugin-react-hooks/lints/globals.md
@@ -0,0 +1,84 @@
+---
+title: globals
+---
+
+
+
+Validates against assignment/mutation of globals during render, part of ensuring that [side effects must run outside of render](/reference/rules/components-and-hooks-must-be-pure#side-effects-must-run-outside-of-render).
+
+
+
+## Rule Details {/*rule-details*/}
+
+Global variables exist outside React's control. When you modify them during render, you break React's assumption that rendering is pure. This can cause components to behave differently in development vs production, break Fast Refresh, and make your app impossible to optimize with features like React Compiler.
+
+### Invalid {/*invalid*/}
+
+Examples of incorrect code for this rule:
+
+```js
+// ❌ Global counter
+let renderCount = 0;
+function Component() {
+ renderCount++; // Mutating global
+ return
+ );
+}
+```
+
+### I need to update nested objects {/*update-nested-objects*/}
+
+Mutating nested properties doesn't trigger re-renders:
+
+```js
+// ❌ Wrong: Mutating nested object
+function UserProfile() {
+ const [user, setUser] = useState({
+ name: 'Alice',
+ settings: {
+ theme: 'light',
+ notifications: true
+ }
+ });
+
+ const toggleTheme = () => {
+ user.settings.theme = 'dark'; // Mutation!
+ setUser(user); // Same object reference
+ };
+}
+```
+
+Spread at each level that needs updating:
+
+```js
+// ✅ Better: Create new objects at each level
+function UserProfile() {
+ const [user, setUser] = useState({
+ name: 'Alice',
+ settings: {
+ theme: 'light',
+ notifications: true
+ }
+ });
+
+ const toggleTheme = () => {
+ setUser({
+ ...user,
+ settings: {
+ ...user.settings,
+ theme: 'dark'
+ }
+ });
+ };
+}
+```
\ No newline at end of file
diff --git a/src/content/reference/eslint-plugin-react-hooks/lints/incompatible-library.md b/src/content/reference/eslint-plugin-react-hooks/lints/incompatible-library.md
new file mode 100644
index 00000000000..e057e1978d9
--- /dev/null
+++ b/src/content/reference/eslint-plugin-react-hooks/lints/incompatible-library.md
@@ -0,0 +1,138 @@
+---
+title: incompatible-library
+---
+
+
+
+Validates against usage of libraries which are incompatible with memoization (manual or automatic).
+
+
+
+
+
+These libraries were designed before React's memoization rules were fully documented. They made the correct choices at the time to optimize for ergonomic ways to keep components just the right amount of reactive as app state changes. While these legacy patterns worked, we have since discovered that it's incompatible with React's programming model. We will continue working with library authors to migrate these libraries to use patterns that follow the Rules of React.
+
+
+
+## Rule Details {/*rule-details*/}
+
+Some libraries use patterns that aren't supported by React. When the linter detects usages of these APIs from a [known list](https://github.com/facebook/react/blob/main/compiler/packages/babel-plugin-react-compiler/src/HIR/DefaultModuleTypeProvider.ts), it flags them under this rule. This means that React Compiler can automatically skip over components that use these incompatible APIs, in order to avoid breaking your app.
+
+```js
+// Example of how memoization breaks with these libraries
+function Form() {
+ const { watch } = useForm();
+
+ // ❌ This value will never update, even when 'name' field changes
+ const name = useMemo(() => watch('name'), [watch]);
+
+ return
Name: {name}
; // UI appears "frozen"
+}
+```
+
+React Compiler automatically memoizes values following the Rules of React. If something breaks with manual `useMemo`, it will also break the compiler's automatic optimization. This rule helps identify these problematic patterns.
+
+
+
+#### Designing APIs that follow the Rules of React {/*designing-apis-that-follow-the-rules-of-react*/}
+
+One question to think about when designing a library API or hook is whether calling the API can be safely memoized with `useMemo`. If it can't, then both manual and React Compiler memoizations will break your user's code.
+
+For example, one such incompatible pattern is "interior mutability". Interior mutability is when an object or function keeps its own hidden state that changes over time, even though the reference to it stays the same. Think of it like a box that looks the same on the outside but secretly rearranges its contents. React can't tell anything changed because it only checks if you gave it a different box, not what's inside. This breaks memoization, since React relies on the outer object (or function) changing if part of its value has changed.
+
+As a rule of thumb, when designing React APIs, think about whether `useMemo` would break it:
+
+```js
+function Component() {
+ const { someFunction } = useLibrary();
+ // it should always be safe to memoize functions like this
+ const result = useMemo(() => someFunction(), [someFunction]);
+}
+```
+
+Instead, design APIs that return immutable state and use explicit update functions:
+
+```js
+// ✅ Good: Return immutable state that changes reference when updated
+function Component() {
+ const { field, updateField } = useLibrary();
+ // this is always safe to memo
+ const greeting = useMemo(() => `Hello, ${field.name}!`, [field.name]);
+
+ return (
+
;
+}
+```
+
+
+
+#### MobX {/*mobx*/}
+
+MobX patterns like `observer` also break memoization assumptions, but the linter does not yet detect them. If you rely on MobX and find that your app doesn't work with React Compiler, you may need to use the `"use no memo" directive`.
+
+```js
+// ❌ MobX `observer`
+const Component = observer(() => {
+ const [timer] = useState(() => new Timer());
+ return Seconds passed: {timer.secondsPassed};
+});
+```
+
+
+
+### Valid {/*valid*/}
+
+Examples of correct code for this rule:
+
+```js
+// ✅ For react-hook-form, use `useWatch`:
+function Component() {
+ const {register, control} = useForm();
+ const watchedValue = useWatch({
+ control,
+ name: 'field'
+ });
+
+ return (
+ <>
+
+
Current value: {watchedValue}
+
+ );
+}
+```
+
+Some other libraries do not yet have alternative APIs that are compatible with React's memoization model. If the linter doesn't automatically skip over your components or hooks that call these APIs, please [file an issue](https://github.com/facebook/react/issues) so we can add it to the linter.
diff --git a/src/content/reference/eslint-plugin-react-hooks/lints/preserve-manual-memoization.md b/src/content/reference/eslint-plugin-react-hooks/lints/preserve-manual-memoization.md
new file mode 100644
index 00000000000..93b582b1e16
--- /dev/null
+++ b/src/content/reference/eslint-plugin-react-hooks/lints/preserve-manual-memoization.md
@@ -0,0 +1,93 @@
+---
+title: preserve-manual-memoization
+---
+
+
+
+Validates that existing manual memoization is preserved by the compiler. React Compiler will only compile components and hooks if its inference [matches or exceeds the existing manual memoization](/learn/react-compiler/introduction#what-should-i-do-about-usememo-usecallback-and-reactmemo).
+
+
+
+## Rule Details {/*rule-details*/}
+
+React Compiler preserves your existing `useMemo`, `useCallback`, and `React.memo` calls. If you've manually memoized something, the compiler assumes you had a good reason and won't remove it. However, incomplete dependencies prevent the compiler from understanding your code's data flow and applying further optimizations.
+
+### Invalid {/*invalid*/}
+
+Examples of incorrect code for this rule:
+
+```js
+// ❌ Missing dependencies in useMemo
+function Component({ data, filter }) {
+ const filtered = useMemo(
+ () => data.filter(filter),
+ [data] // Missing 'filter' dependency
+ );
+
+ return ;
+}
+
+// ❌ Missing dependencies in useCallback
+function Component({ onUpdate, value }) {
+ const handleClick = useCallback(() => {
+ onUpdate(value);
+ }, [onUpdate]); // Missing 'value'
+
+ return ;
+}
+```
+
+### Valid {/*valid*/}
+
+Examples of correct code for this rule:
+
+```js
+// ✅ Complete dependencies
+function Component({ data, filter }) {
+ const filtered = useMemo(
+ () => data.filter(filter),
+ [data, filter] // All dependencies included
+ );
+
+ return ;
+}
+
+// ✅ Or let the compiler handle it
+function Component({ data, filter }) {
+ // No manual memoization needed
+ const filtered = data.filter(filter);
+ return ;
+}
+```
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Should I remove my manual memoization? {/*remove-manual-memoization*/}
+
+You might wonder if React Compiler makes manual memoization unnecessary:
+
+```js
+// Do I still need this?
+function Component({items, sortBy}) {
+ const sorted = useMemo(() => {
+ return [...items].sort((a, b) => {
+ return a[sortBy] - b[sortBy];
+ });
+ }, [items, sortBy]);
+
+ return ;
+}
+```
+
+You can safely remove it if using React Compiler:
+
+```js
+// ✅ Better: Let the compiler optimize
+function Component({items, sortBy}) {
+ const sorted = [...items].sort((a, b) => {
+ return a[sortBy] - b[sortBy];
+ });
+
+ return ;
+}
+```
\ No newline at end of file
diff --git a/src/content/reference/eslint-plugin-react-hooks/lints/purity.md b/src/content/reference/eslint-plugin-react-hooks/lints/purity.md
new file mode 100644
index 00000000000..af8aacc612d
--- /dev/null
+++ b/src/content/reference/eslint-plugin-react-hooks/lints/purity.md
@@ -0,0 +1,83 @@
+---
+title: purity
+---
+
+
+
+Validates that [components/hooks are pure](/reference/rules/components-and-hooks-must-be-pure) by checking that they do not call known-impure functions.
+
+
+
+## Rule Details {/*rule-details*/}
+
+React components must be pure functions - given the same props, they should always return the same JSX. When components use functions like `Math.random()` or `Date.now()` during render, they produce different output each time, breaking React's assumptions and causing bugs like hydration mismatches, incorrect memoization, and unpredictable behavior.
+
+## Common Violations {/*common-violations*/}
+
+In general, any API that returns a different value for the same inputs violates this rule. Usual examples include:
+
+- `Math.random()`
+- `Date.now()` / `new Date()`
+- `crypto.randomUUID()`
+- `performance.now()`
+
+### Invalid {/*invalid*/}
+
+Examples of incorrect code for this rule:
+
+```js
+// ❌ Math.random() in render
+function Component() {
+ const id = Math.random(); // Different every render
+ return
;
+}
+```
+
+### Valid {/*valid*/}
+
+Examples of correct code for this rule:
+
+```js
+// ✅ Stable IDs from initial state
+function Component() {
+ const [id] = useState(() => crypto.randomUUID());
+ return
Content
;
+}
+```
+
+## Troubleshooting {/*troubleshooting*/}
+
+### I need to show the current time {/*current-time*/}
+
+Calling `Date.now()` during render makes your component impure:
+
+```js {expectedErrors: {'react-compiler': [3]}}
+// ❌ Wrong: Time changes every render
+function Clock() {
+ return
;
+}
+```
\ No newline at end of file
diff --git a/src/content/reference/eslint-plugin-react-hooks/lints/refs.md b/src/content/reference/eslint-plugin-react-hooks/lints/refs.md
new file mode 100644
index 00000000000..3108fdd89da
--- /dev/null
+++ b/src/content/reference/eslint-plugin-react-hooks/lints/refs.md
@@ -0,0 +1,115 @@
+---
+title: refs
+---
+
+
+
+Validates correct usage of refs, not reading/writing during render. See the "pitfalls" section in [`useRef()` usage](/reference/react/useRef#usage).
+
+
+
+## Rule Details {/*rule-details*/}
+
+Refs hold values that aren't used for rendering. Unlike state, changing a ref doesn't trigger a re-render. Reading or writing `ref.current` during render breaks React's expectations. Refs might not be initialized when you try to read them, and their values can be stale or inconsistent.
+
+## How It Detects Refs {/*how-it-detects-refs*/}
+
+The lint only applies these rules to values it knows are refs. A value is inferred as a ref when the compiler sees any of the following patterns:
+
+- Returned from `useRef()` or `React.createRef()`.
+
+ ```js
+ const scrollRef = useRef(null);
+ ```
+
+- An identifier named `ref` or ending in `Ref` that reads from or writes to `.current`.
+
+ ```js
+ buttonRef.current = node;
+ ```
+
+- Passed through a JSX `ref` prop (for example ``).
+
+ ```jsx
+
+ ```
+
+Once something is marked as a ref, that inference follows the value through assignments, destructuring, or helper calls. This lets the lint surface violations even when `ref.current` is accessed inside another function that received the ref as an argument.
+
+## Common Violations {/*common-violations*/}
+
+- Reading `ref.current` during render
+- Updating `refs` during render
+- Using `refs` for values that should be state
+
+### Invalid {/*invalid*/}
+
+Examples of incorrect code for this rule:
+
+```js
+// ❌ Reading ref during render
+function Component() {
+ const ref = useRef(0);
+ const value = ref.current; // Don't read during render
+ return
{value}
;
+}
+
+// ❌ Modifying ref during render
+function Component({value}) {
+ const ref = useRef(null);
+ ref.current = value; // Don't modify during render
+ return ;
+}
+```
+
+### Valid {/*valid*/}
+
+Examples of correct code for this rule:
+
+```js
+// ✅ Read ref in effects/handlers
+function Component() {
+ const ref = useRef(null);
+
+ useEffect(() => {
+ if (ref.current) {
+ console.log(ref.current.offsetWidth); // OK in effect
+ }
+ });
+
+ return ;
+}
+
+// ✅ Use state for UI values
+function Component() {
+ const [count, setCount] = useState(0);
+
+ return (
+
+ );
+}
+
+// ✅ Lazy initialization of ref value
+function Component() {
+ const ref = useRef(null);
+
+ // Initialize only once on first use
+ if (ref.current === null) {
+ ref.current = expensiveComputation(); // OK - lazy initialization
+ }
+
+ const handleClick = () => {
+ console.log(ref.current); // Use the initialized value
+ };
+
+ return ;
+}
+```
+
+## Troubleshooting {/*troubleshooting*/}
+
+### The lint flagged my plain object with `.current` {/*plain-object-current*/}
+
+The name heuristic intentionally treats `ref.current` and `fooRef.current` as real refs. If you're modeling a custom container object, pick a different name (for example, `box`) or move the mutable value into state. Renaming avoids the lint because the compiler stops inferring it as a ref.
diff --git a/src/content/reference/eslint-plugin-react-hooks/lints/rules-of-hooks.md b/src/content/reference/eslint-plugin-react-hooks/lints/rules-of-hooks.md
new file mode 100644
index 00000000000..6508fc867f2
--- /dev/null
+++ b/src/content/reference/eslint-plugin-react-hooks/lints/rules-of-hooks.md
@@ -0,0 +1,161 @@
+---
+title: rules-of-hooks
+---
+
+
+
+Validates that components and hooks follow the [Rules of Hooks](/reference/rules/rules-of-hooks).
+
+
+
+## Rule Details {/*rule-details*/}
+
+React relies on the order in which hooks are called to correctly preserve state between renders. Each time your component renders, React expects the exact same hooks to be called in the exact same order. When hooks are called conditionally or in loops, React loses track of which state corresponds to which hook call, leading to bugs like state mismatches and "Rendered fewer/more hooks than expected" errors.
+
+## Common Violations {/*common-violations*/}
+
+These patterns violate the Rules of Hooks:
+
+- **Hooks in conditions** (`if`/`else`, ternary, `&&`/`||`)
+- **Hooks in loops** (`for`, `while`, `do-while`)
+- **Hooks after early returns**
+- **Hooks in callbacks/event handlers**
+- **Hooks in async functions**
+- **Hooks in class methods**
+- **Hooks at module level**
+
+
+
+### `use` hook {/*use-hook*/}
+
+The `use` hook is different from other React hooks. You can call it conditionally and in loops:
+
+```js
+// ✅ `use` can be conditional
+if (shouldFetch) {
+ const data = use(fetchPromise);
+}
+
+// ✅ `use` can be in loops
+for (const promise of promises) {
+ results.push(use(promise));
+}
+```
+
+However, `use` still has restrictions:
+- Can't be wrapped in try/catch
+- Must be called inside a component or hook
+
+Learn more: [`use` API Reference](/reference/react/use)
+
+
+
+### Invalid {/*invalid*/}
+
+Examples of incorrect code for this rule:
+
+```js
+// ❌ Hook in condition
+if (isLoggedIn) {
+ const [user, setUser] = useState(null);
+}
+
+// ❌ Hook after early return
+if (!data) return ;
+const [processed, setProcessed] = useState(data);
+
+// ❌ Hook in callback
+