---
name: react19-compiler-typescript
description: Enforce idiomatic React 19 + TypeScript conventions built around the React Compiler's automatic memoization. Use this any time writing, generating, reviewing, or refactoring React components, hooks, or props in TypeScript/TSX — including code that manually wraps things in useMemo/useCallback/React.memo, uses forwardRef, mutates props/state, or needs typing for Actions, useOptimistic, use(), or refs. Trigger even if the user didn't say "React 19" or "compiler" explicitly; it applies whenever React component/hook code is being written or optimized.
---

# React 19 + TypeScript with the React Compiler

## Why this matters

React Compiler (stable since React Compiler 1.0, October 2025) rewrites your components
and hooks at build time, inserting memoization equivalent to `useMemo`/`useCallback`/
`React.memo` automatically and more granularly than a human would by hand. It ships as
`babel-plugin-react-compiler`, and its lint rules live inside `eslint-plugin-react-hooks`
(recommended preset) so linting and compilation share one source of truth.

The practical consequence: **manual memoization is no longer the default** — it's
either redundant, or actively harmful if it doesn't match what the compiler would have
inferred (the compiler bails out silently rather than risk breaking your app). Writing
"optimized" React in 2026 means writing _plain, rule-following_ React and trusting the
build step, not sprinkling `useMemo` everywhere out of habit.

This skill assumes and builds on the base `typescript-strict-typing` skill for general
typing discipline (no `any`, `interface` for entities, discriminated unions for variant
state, etc.) — apply both together.

## Core principle

> Write plain, obviously-pure React. Let the compiler memoize. The Rules of React are no
> longer just style guidance — the compiler's correctness depends on you following them.

---

## 1. Stop hand-rolling memoization

> ⚠️ **Everything in this section assumes the compiler is confirmed active** (wired per
> §7, verified via the "Memo ✨" badge in §8). If you drop manual memoization _without_
> that confirmation, you don't get automatic memoization to replace it — you get
> **neither**. That's not a correctness bug (React still renders the right output), but
> every child re-renders on every parent render regardless of whether its props
> actually changed, and every inline computation reruns every render with nothing
> caching it. It's the pre-memoization default behavior of React — often invisible in
> small trees, but a real source of jank in large lists, heavy computations, or deep
> trees under a frequently-re-rendering parent. If you're not certain the compiler is
> active yet, keep existing manual memoization until you've verified it, then remove it.

Don't reach for `useMemo`, `useCallback`, or `React.memo` by default — the compiler adds
this automatically wherever it determines it helps.

```tsx
// ❌ Old habit — noisy, and a mismatched dependency array is a whole class of bugs
const filteredUsers = useMemo(() => users.filter((u) => u.isActive), [users]);
const handleClick = useCallback(() => onSelect(user.id), [onSelect, user.id]);

// ✅ New default — just write the logic; the compiler memoizes what's worth memoizing
const filteredUsers = users.filter((u) => u.isActive);
const handleClick = () => onSelect(user.id);
```

Manual memoization is still justified, narrowly, when:

- You've **confirmed a compiler bail-out** (see §6) on a genuine hot path via profiling,
  and fixing the underlying Rules-of-React violation isn't possible right now.
- A value must have **stable referential identity across a boundary the compiler can't
  see** — e.g. passed into a non-React library, a WebSocket subscription, or a
  third-party hook incompatible with the compiler (`react-hook-form`'s `useForm`,
  `@tanstack/react-table`'s `useReactTable` are known cases).
- Keep any manual memoization it produces isolated and commented with _why_, so it
  doesn't silently rot into a bail-out later when the code around it changes.

## 2. The Rules of React are now load-bearing

The compiler assumes your components and hooks are pure. Violating these rules doesn't
just risk a subtle bug anymore — it causes the compiler to silently skip optimizing that
component:

- **Idempotent renders** — given the same props/state/context, a component must return
  the same output. No random values, no `Date.now()`, no side effects during render.
- **Immutability** — never mutate props, state, or context directly. Always create new
  objects/arrays for changes.
- **Side effects only in effects or event handlers** — never during render.
- **Hooks called unconditionally, top-level, same order every render** — no hooks inside
  conditionals, loops, or nested functions.

```tsx
// ❌ Mutates a prop — breaks purity and the compiler can't safely memoize this
function TodoList({ todos }: { todos: Todo[] }) {
  todos.sort((a, b) => a.priority - b.priority); // mutates caller's array
  return (
    <ul>
      {todos.map((t) => (
        <li key={t.id}>{t.title}</li>
      ))}
    </ul>
  );
}

// ✅ Creates a new array — pure, compiler-safe
function TodoList({ todos }: { todos: Todo[] }) {
  const sorted = [...todos].sort((a, b) => a.priority - b.priority);
  return (
    <ul>
      {sorted.map((t) => (
        <li key={t.id}>{t.title}</li>
      ))}
    </ul>
  );
}
```

## 3. Naming conventions the compiler relies on

The compiler identifies what to optimize by naming heuristics, same as the Rules of
Hooks linter:

| Kind                                                                     | Convention                      | Notes                                                                         |
| ------------------------------------------------------------------------ | ------------------------------- | ----------------------------------------------------------------------------- |
| Components                                                               | `PascalCase`, returns JSX       | Compiler treats it as a component to optimize                                 |
| Custom hooks                                                             | `camelCase`, prefixed `use`     | Required for both Rules-of-Hooks lint and compiler analysis                   |
| Plain helper functions that return JSX-like values but aren't components | Avoid `PascalCase`/`use` naming | Prevents the compiler (and other devs) from mistaking it for a component/hook |

## 4. Typing React 19 primitives

**`ref` as a normal prop** — `forwardRef` is no longer required for most cases; function
components can accept `ref` directly.

```tsx
type InputProps = {
  ref?: React.Ref<HTMLInputElement>;
  placeholder?: string;
};

function TextInput({ ref, placeholder }: InputProps) {
  return <input ref={ref} placeholder={placeholder} />;
}
```

**Actions with `useActionState`** — type the state and payload as generics; model the
result as a discriminated union (per the base typing skill) rather than optional fields.

```tsx
type FormState = { status: 'idle' } | { status: 'error'; message: string } | { status: 'success' };

const [state, formAction, isPending] = useActionState<FormState, FormData>(
  async (_previous, formData) => {
    const email = formData.get('email');
    if (typeof email !== 'string' || !email.includes('@')) {
      return { status: 'error', message: 'Invalid email' };
    }
    await submit(email);
    return { status: 'success' };
  },
  { status: 'idle' },
);
```

**Optimistic updates with `useOptimistic`** — type both the state and the update shape.

```tsx
const [optimisticTodos, addOptimisticTodo] = useOptimistic<Todo[], Todo>(
  todos,
  (state, newTodo) => [...state, newTodo],
);
```

**Reading a promise or context with `use()`** — type the resolved value, not the
promise wrapper; `use()` is not a hook and may be called conditionally.

```tsx
function Comments({ commentsPromise }: { commentsPromise: Promise<Comment[]> }) {
  const comments = use(commentsPromise); // suspends until resolved
  return (
    <ul>
      {comments.map((c) => (
        <li key={c.id}>{c.text}</li>
      ))}
    </ul>
  );
}
```

**Stable event callbacks with `useEffectEvent`** (React 19.2+) — separates "event"
logic from "reactive" effect logic so the callback always sees the latest props/state
without being listed as an effect dependency. Needs `eslint-plugin-react-hooks@6+` to
lint correctly.

```tsx
const onVisit = useEffectEvent((url: string) => {
  logVisit(url, theme); // always fresh `theme`, never re-triggers the effect
});

useEffect(() => {
  onVisit(url);
}, [url]); // `theme` intentionally omitted — onVisit is stable
```

## 5. Compiler-friendly render patterns

- Creating new object/array/function literals inline in render (`style={{ color }}`,
  `onClick={() => ...}`) is fine — stop manually hoisting or `useMemo`-wrapping these
  preemptively; the compiler memoizes them if it determines it's worthwhile.
- Avoid module-level mutable variables read or written during render — that state is
  invisible to the compiler and breaks idempotence.
- Don't use `useRef` to store a value that should trigger a re-render when it changes —
  refs are an imperative escape hatch, not state, and the compiler treats them as such.
- Keep components small and composable. The compiler optimizes per component/hook
  boundary, so a single 300-line component gives it far less to work with than several
  focused ones.

## 6. Typing props (builds on `typescript-strict-typing`)

- `interface` for a component's `Props` — it's an entity shape, often extended.
- A discriminated union when a component has mutually exclusive prop combinations,
  instead of a pile of optional props that can contradict each other.

```tsx
// ❌ Bad — nothing stops passing both `href` and `onClick` incoherently
interface ButtonProps {
  label: string;
  href?: string;
  onClick?: () => void;
}

// ✅ Good — the two variants can't be mixed
type ButtonProps =
  | { variant: 'link'; label: string; href: string }
  | { variant: 'action'; label: string; onClick: () => void };
```

## 7. Tooling setup

**The compiler is opt-in — no default setup enables it automatically.** Plain
`@vitejs/plugin-react` (`react()`), plain Next.js, plain Babel/webpack config, etc. do
**not** run the compiler on their own. Verify it's actually wired up before assuming any
of the memoization guidance above applies to your build.

```bash
# Compiler (build-time transform)
npm install --save-dev --save-exact babel-plugin-react-compiler@latest
```

**Lint rules — oxlint.** Oxlint ships a **native, Rust-based** `react/react-compiler`
rule that runs the same compiler analysis in lint-only mode — same diagnostics as the
Babel-based ESLint version, no Babel needed for linting. It's experimental and **off by
default**, so it has to be enabled explicitly:

```json
// .oxlintrc.json
{
  "plugins": ["react"],
  "rules": {
    "react/react-compiler": "error"
  }
}
```

This single rule reports two distinct things — both worth fixing, but for different
reasons:

- **Rules-of-React violations** (conditional hooks, reading a ref during render, mutating
  props) — these are real bugs, independent of the compiler.
- **Compiler bail-outs** — places the compiler declined to optimize (e.g. unsupported
  syntax) without a rule violation. Not incorrect code, just a missed optimization —
  lower priority than a violation, but worth knowing about on a hot path.

If you'd rather use an existing ESLint plugin's rules through oxlint instead of the
native one (e.g. to match a team convention), oxlint's `jsPlugins` can load
`eslint-plugin-react-hooks` directly — slower than the native rule since it still runs
through Babel, but useful if you need a rule the native port doesn't cover yet:

```json
{
  "jsPlugins": [{ "name": "react-hooks-js", "specifier": "eslint-plugin-react-hooks" }],
  "rules": { "react-hooks-js/set-state-in-render": "error" }
}
```

**Lint rules — ESLint** (if not on oxlint): the same rules ship inside
`eslint-plugin-react-hooks`.

```bash
npm install --save-dev eslint-plugin-react-hooks@latest
```

```js
// eslint.config.js
import reactHooks from 'eslint-plugin-react-hooks';
import { defineConfig } from 'eslint/config';

export default defineConfig([reactHooks.configs.flat.recommended]);
```

**Wiring it into Vite 8.** `@vitejs/plugin-react` v6+ (the version that ships with Vite 8) switched its default transform from Babel to oxc for speed, so the compiler is
**never** on by default and the old `react({ babel: {...} })` option **does not work**
on this setup — it's silently ignored, not an error, which is an easy way to think the
compiler is running when it isn't. Wire it in explicitly, as a separate Babel pass that
runs before `react()`:

```js
// vite.config.js
import { defineConfig } from 'vite';
import react, { reactCompilerPreset } from '@vitejs/plugin-react';
import babel from '@rolldown/plugin-babel';

export default defineConfig({
  plugins: [
    babel({ presets: [reactCompilerPreset()] }), // must run before react()
    react(),
  ],
});
```

```bash
npm install --save-dev @rolldown/plugin-babel @babel/core babel-plugin-react-compiler
npm install --save-dev @types/babel__core   # if using TypeScript
```

`reactCompilerPreset()` is a helper exported from `@vitejs/plugin-react` itself — it
bundles `babel-plugin-react-compiler` with sane default include/exclude filters so you
don't have to hand-roll a Babel preset. It optionally accepts:

- `compilationMode: 'annotation'` — only compile components explicitly marked with a
  `"use memo"` directive, instead of the whole codebase (useful for a gradual rollout).
- `target: '17' | '18'` — if any part of the app still runs on an older React major and
  needs the `react-compiler-runtime` package instead of `react/compiler-runtime`.

After adding this, confirm it's actually active via the React DevTools "Memo ✨" badge
(§8) before trusting the "don't hand-roll memoization" guidance in §1 — a silently
misconfigured Babel order (`react()` before `babel()`) is a common way for this to look
wired up but do nothing.

- Treat compiler-related lint errors (Rules-of-React violations, mismatched manual
  memoization) as must-fix, not optional — an unfixed violation means that component
  silently gets **zero** compiler optimization.
- For a large existing codebase, adopt incrementally by scoping the babel plugin to a
  directory (e.g. a UI component library) before enabling it globally.
- If a specific function is genuinely incompatible with the compiler (e.g. it calls
  `useForm` from `react-hook-form`), opt it out with the `"use no memo"` directive as
  the **first line of the function body** — it's a temporary escape hatch, not a
  permanent fix, so leave a comment explaining why.

```tsx
function LegacyForm() {
  'use no memo';
  const form = useForm(); // incompatible with the compiler today
  // ...
}
```

## 8. Checking whether the compiler is actually optimizing

- **React DevTools** — an optimized component shows a "Memo ✨" badge next to its name
  in the component tree.
- **ESLint** — the compiler's recommended rules flag Rules-of-React violations at lint
  time, before they ever become a silent runtime bail-out.
- A bail-out is not a crash — it just means that specific component/hook is running
  unoptimized. Treat a missing "Memo ✨" badge on a component you expect to be optimized
  as a signal to check for a Rules-of-React violation, not a compiler bug.

---

## Review checklist

- [ ] Compiler confirmed active ("Memo ✨" badge) before removing any _existing_ manual
      memoization — don't strip it on faith
- [ ] No new `useMemo`/`useCallback`/`React.memo` added without a documented reason
      (confirmed bail-out, or a boundary the compiler can't see through)
- [ ] No prop/state/context mutation anywhere in render
- [ ] All hooks called unconditionally at the top level, same order every render
- [ ] Side effects live in `useEffect`/event handlers, never during render
- [ ] Components are `PascalCase`; hooks are `camelCase` and prefixed `use`
- [ ] `ref` accepted as a normal prop instead of `forwardRef`, unless targeting a version
      that requires it
- [ ] Action/optimistic-update state modeled as a discriminated union, not optional
      fields
- [ ] Mutually exclusive prop combinations modeled as a discriminated union `Props` type
- [ ] `eslint-plugin-react-hooks` recommended config enabled and passing
- [ ] Any `"use no memo"` usage has a comment explaining why

## Quick reference

| Situation                                                      | Do                                                            |
| -------------------------------------------------------------- | ------------------------------------------------------------- |
| Tempted to write `useMemo`/`useCallback`                       | Don't — write the plain expression, let the compiler decide   |
| Need a ref on a function component                             | Accept `ref` as a prop, skip `forwardRef`                     |
| Form/async state with distinct outcomes                        | Discriminated union via `useActionState`, not optional fields |
| Callback needs latest props/state without re-running an effect | `useEffectEvent`                                              |
| A hook/library is known-incompatible with the compiler         | `"use no memo"` at the top of that function, with a comment   |
| Checking if optimization is happening                          | React DevTools "Memo ✨" badge + compiler ESLint rules        |