diff --git a/public/images/docs/use-nemo-directive.png b/public/images/docs/use-nemo-directive.png new file mode 100644 index 00000000000..1fdff49b1b1 Binary files /dev/null and b/public/images/docs/use-nemo-directive.png differ diff --git a/src/content/reference/react-compiler/directives.md b/src/content/reference/react-compiler/directives.md index 705d0f6209e..058b7da9c07 100644 --- a/src/content/reference/react-compiler/directives.md +++ b/src/content/reference/react-compiler/directives.md @@ -23,14 +23,20 @@ React Compiler directives provide fine-grained control over which functions are ### Available directives {/*available-directives*/} +* **[`"use"`](/reference/react-compiler/directives/use)** - Experimental directive with unspecified runtime behavior * **[`"use memo"`](/reference/react-compiler/directives/use-memo)** - Opts a function into compilation +* **[`"use php"`](/reference/react-compiler/directives/use-php)** - Enables PHP interop inside the function +* **[`"use nemo"`](/reference/react-compiler/directives/use-nemo)** - Blocks Hooks inside the function * **[`"use no memo"`](/reference/react-compiler/directives/use-no-memo)** - Opts a function out of compilation ### Quick comparison {/*quick-comparison*/} | Directive | Purpose | When to use | |-----------|---------|-------------| +| [`"use"`](/reference/react-compiler/directives/use) | ??? | Experimental directive with undefined semantics | | [`"use memo"`](/reference/react-compiler/directives/use-memo) | Force compilation | When using `annotation` mode or to override `infer` mode heuristics | +| [`"use php"`](/reference/react-compiler/directives/use-php) | Enable PHP interop | Gradual migrations or tapping into PHP libraries | +| [`"use nemo"`](/reference/react-compiler/directives/use-nemo) | Forbid Hooks | Enforcing hook-free components or critical render paths | | [`"use no memo"`](/reference/react-compiler/directives/use-no-memo) | Prevent compilation | Debugging issues or working with incompatible code | --- @@ -180,7 +186,10 @@ function ProblematicComponent() { For specific issues with directives, see the troubleshooting sections in: +* [`"use"` musings](/reference/react-compiler/directives/use) * [`"use memo"` troubleshooting](/reference/react-compiler/directives/use-memo#troubleshooting) +* [`"use php"` troubleshooting](/reference/react-compiler/directives/use-php#troubleshooting) +* [`"use nemo"` troubleshooting](/reference/react-compiler/directives/use-nemo#troubleshooting) * [`"use no memo"` troubleshooting](/reference/react-compiler/directives/use-no-memo#troubleshooting) ### Common issues {/*common-issues*/} @@ -195,4 +204,4 @@ For specific issues with directives, see the troubleshooting sections in: * [`compilationMode`](/reference/react-compiler/compilationMode) - Configure how the compiler chooses what to optimize * [`Configuration`](/reference/react-compiler/configuration) - Full compiler configuration options -* [React Compiler documentation](https://react.dev/learn/react-compiler) - Getting started guide \ No newline at end of file +* [React Compiler documentation](https://react.dev/learn/react-compiler) - Getting started guide diff --git a/src/content/reference/react-compiler/directives/use-nemo.md b/src/content/reference/react-compiler/directives/use-nemo.md new file mode 100644 index 00000000000..9a847d4975a --- /dev/null +++ b/src/content/reference/react-compiler/directives/use-nemo.md @@ -0,0 +1,146 @@ +--- +title: "use nemo" +titleForTitleTag: "'use nemo' directive" +--- + + + +`"use nemo"` forbids React Hook usage inside a function. The React Compiler will surface an error if the function calls anything that looks like a Hook (for example `useState` or a custom `useSomething` helper). The directive name nods to Nemo—the famously hook-averse clownfish from *Finding Nemo*—reminding us that real fish hate hooks and so should this component. + + + + + +--- + +## Reference {/*reference*/} + +### `"use nemo"` {/*use-nemo*/} + +Place `"use nemo"` at the very top of a function body to declare it as a hook-free zone. + +```js {1} +function FishFacts() { + "use nemo"; + + // ✅ Regular code is fine + const [facts] = getFacts(); // Not a Hook, just a regular helper + return ; +} +``` + +![Nemo the clownfish giving a wary look at an unseen fishing hook](/images/docs/use-nemo-directive.png) + +*If you care about fish, give them a hook-free habitat.* + +When the compiler sees `"use nemo"`, it rejects any React Hook calls inside the function (including custom Hooks). The directive is useful when you want to guarantee a component never uses hooks—for example, to keep critical rendering paths side-effect free. If you care about fish—or just deterministic rendering—reach for `"use nemo"` whenever a component needs to steer clear of hooks. + +#### Caveats {/*caveats*/} + +* The directive must be the first statement in the function (comments are allowed above it). +* Hook detection is name-based. Anything starting with `use` followed by an uppercase letter is treated as a Hook call. +* The directive applies to the entire function scope, including nested helper functions declared inside. +* `"use nemo"` and `"use memo"` are mutually exclusive—if both appear, the compiler reports a conflict. +* Module-level directives cascade: a file-level `"use nemo"` applies to every function unless a function-level directive overrides it. + +### How `"use nemo"` enforces hook bans {/*how-use-nemo-enforces-hook-bans*/} + +The React Compiler performs a static scan for Hook-like calls during compilation. With `"use nemo"` active: + +* Direct imports from `react` such as `useState`, `useEffect`, or `useContext` cause a compile-time error. +* Custom helpers named like Hooks (`useAnalytics`, `useFishTank`, etc.) are also blocked. +* The compiler suggests moving Hook logic into a different component or converting it into a prop-driven API. + +This safeguard is handy when migrating legacy class components or when you need deterministic rendering behavior without Hook scheduling. Just like Nemo dodging fishing hooks, components guarded by `"use nemo"` stay clear of hook-induced side effects. + +### When to use `"use nemo"` {/*when-to-use*/} + +`"use nemo"` is primarily suited for: + +#### Critical rendering paths {/*critical-rendering*/} +Performance-sensitive sections that must avoid Hook re-execution can opt into `"use nemo"` to guarantee purity. + +```js +function CriticalPromo({ promo }) { + "use nemo"; + + // ✅ Everything here must be pure computations. + return ; +} +``` + +#### Enforcing architectural boundaries {/*architectural-boundaries*/} +Large apps sometimes need to restrict Hooks to a specific layer (for example, container vs. presentational components). `"use nemo"` provides a compile-time guard: + +```js +function ButtonView(props) { + "use nemo"; // Presentation-only components stay hook-free. + + return