Requirements

Always use destructured props in function parameters
Define TypeScript types inline with the destructured props
Avoid creating separate interfaces for component props
Avoid non-destructured props that require additional destructuring inside the component
Use available UI components from the component library
Use CSS variables from globals.css for consistent theming
Use Tailwind v4 syntax (see Tailwind v4 Syntax)
DO NOT add icon margin in Button, DropdownMenuItem: use gap-2 instead
Use useEffectEvent to extract non-reactive logic from Effects (see Separating Events from Effects)
NEVER suppress the dependency linter with eslint-disable - use useEffectEvent instead
Use custom breakpoint syntax for responsive design (see App-Specific Rules)

Tailwind v4 Syntax

Inline opacity: Use / for opacity (bg-black/50 text-white/80)
- v3: bg-black bg-opacity-50 text-white text-opacity-80
- Removed: bg-opacity-*, text-opacity-*, border-opacity-*
Renamed utilities: shadow-sm → shadow-xs, rounded-sm → rounded-xs, blur-sm → blur-xs
CSS variables: Use parentheses bg-(--brand-color) instead of brackets bg-[--brand-color]
Important modifier: Exclamation mark at the end (size-5!) instead of beginning (!size-5)
Descendant selectors: Use **: for all descendants (replaces [&_*]:) and *: for direct children (replaces [&>*]:)
- All descendants: **:px-4 instead of [&_*]:px-4
- Direct children: *:px-4 instead of [&>*]:px-4
- Element filtering: *:[a]:underline instead of [&>a]:underline, **:[a]:underline instead of [&_a]:underline
- Data attributes: *:data-[slot=field-label]:flex-auto instead of *:[[data-slot=field-label]]:flex-auto. Keep [[data-...]] if there are other selectors.
- Context-aware (in-): in-data-[slot=tooltip-content]:text-background instead of [[data-slot=tooltip-content]_&]:text-background
Composable variants: Chain variants together (group-has-data-selected:opacity-100, data-highlighted:ring-2)
Canonical classes: Always prefer built-in utilities over arbitrary values (e.g., w-full instead of w-[100%], translate-x-full instead of translate-x-[100%])
Default changes: Border color now currentColor (was gray-200), ring width now 1px (was 3px)

Component Patterns

Design Tokens

Design tokens are semantic CSS variables that separate theme, context, and usage. Rather than hardcoding colors, use a semantic naming convention that creates layers of abstraction.

Variable Architecture

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
}

Common tokens:

--background - Page background color
--foreground - General text color
--primary - Main brand color
--primary-foreground - Text color against primary

This creates a maintainable, flexible system that scales across applications.

Data Attribute Styling Patterns

Shadcn/ui and Radix UI components use data attributes (data-state, data-slot) to enable flexible styling without prop explosion. Use these patterns when working with components that expose data attributes.

Styling with data-state

Components expose their state through data-state attributes. Use Tailwind's arbitrary variant syntax to style based on component state:

<Dialog
  className={cn(
    // Base styles
    "rounded-lg border p-4",
    // State-based styles
    "data-[state=open]:animate-in data-[state=open]:fade-in",
    "data-[state=closed]:animate-out data-[state=closed]:fade-out",
    // Multiple attributes
    "data-[state=open][data-side=top]:slide-in-from-top-2",
  )}
/>

For commonly-used states, extend Tailwind's configuration:

module.exports = {
  theme: {
    extend: {
      data: {
        open: 'state="open"',
        closed: 'state="closed"',
        active: 'state="active"',
      },
    },
  },
};

Then use shorthand:

<Dialog className="data-open:opacity-100 data-closed:opacity-0" />

Radix UI Data Attributes

Radix UI automatically applies data attributes to its primitives:

import * as Dialog from "@radix-ui/react-dialog";

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Portal>
    {/* Radix automatically adds data-state="open" | "closed" */}
    <Dialog.Overlay className="data-[state=open]:animate-in data-[state=closed]:animate-out" />
    <Dialog.Content className="data-[state=open]:fade-in data-[state=closed]:fade-out" />
  </Dialog.Portal>
</Dialog.Root>;

Common Radix data attributes:

data-state - open/closed, active/inactive, on/off
data-side - top/right/bottom/left (for positioned elements)
data-align - start/center/end (for positioned elements)
data-orientation - horizontal/vertical
data-disabled - present when disabled
data-placeholder - present when showing placeholder

Common State Patterns

Use data attributes for all kinds of component state:

// Open/closed state
<Accordion data-state={isOpen ? 'open' : 'closed'} />

// Selected state
<Tab data-state={isSelected ? 'active' : 'inactive'} />

// Disabled state (in addition to disabled attribute)
<Button data-disabled={isDisabled} disabled={isDisabled} />

// Loading state
<Button data-loading={isLoading} />

// Orientation
<Slider data-orientation="horizontal" />

// Side/position
<Tooltip data-side="top" />

Using data-slot for Component Targeting

Components use data-slot attributes for stable identifiers that can be targeted by parents.

Using has-[] for parent-aware styling:

<form
  data-slot="form"
  className={cn(
    "space-y-4",
    // Adjust spacing when specific slots are present
    "has-[>[data-slot=form-section]]:space-y-6",
    "has-[>[data-slot=inline-fields]]:space-y-2",
    // Style based on slot states
    "has-[[data-slot=submit-button][data-loading=true]]:opacity-50",
  )}
>
  {children}
</form>

Using [&_] for descendant targeting:

<div
  data-slot="card"
  className={cn(
    "rounded-lg border p-4",
    // Target any descendant with data-slot
    "[&_[data-slot=card-header]]:mb-4",
    "[&_[data-slot=card-title]]:text-lg [&_[data-slot=card-title]]:font-semibold",
    "[&_[data-slot=card-description]]:text-muted-foreground [&_[data-slot=card-description]]:text-sm",
    "[&_[data-slot=card-footer]]:mt-4 [&_[data-slot=card-footer]]:border-t [&_[data-slot=card-footer]]:pt-4",
  )}
>
  {children}
</div>

Global CSS with data-slot

Use global CSS for theme-wide component styling:

/* Style all buttons within forms */
[data-slot="form"] [data-slot="button"] {
  @apply w-full @xl:w-auto;
}

/* Style submit buttons specifically */
[data-slot="form"] [data-slot="submit-button"] {
  @apply bg-primary text-primary-foreground;
}

/* Adjust inputs within inline layouts */
[data-slot="inline-fields"] [data-slot="input"] {
  @apply flex-1;
}

/* Style based on state combinations */
[data-slot="dialog"][data-state="open"] [data-slot="dialog-content"] {
  @apply animate-in fade-in;
}

data-slot Naming Conventions

Follow these conventions for consistent data-slot naming:

Use kebab-case - data-slot="form-field" not data-slot="formField"
Be specific - data-slot="submit-button" not data-slot="button"
Match component purpose - Name reflects what it does, not how it looks
Avoid implementation details - data-slot="user-avatar" not data-slot="rounded-image"

// ✅ Good examples
data-slot="search-input"
data-slot="navigation-menu"
data-slot="error-message"
data-slot="submit-button"
data-slot="card-header"

// ❌ Avoid
data-slot="input"           // Too generic
data-slot="blueButton"      // Includes styling
data-slot="div-wrapper"     // Implementation detail
data-slot="mainContent"     // Use kebab-case

When to Use Data Attributes vs Props

Use data-state for:

Visual states (open/closed, active/inactive, loading)
Layout states (orientation, side, alignment)
Interaction states (hover, focus, disabled when styling children)

Use data-slot for:

Component identification with stable identifiers
Parent-child composition patterns
Theme-wide component styling
Variant-independent targeting

Use props for:

Variants (primary, secondary, destructive)
Sizes (sm, md, lg)
Behavioral configuration (controlled/uncontrolled, defaults)
Event handlers (onClick, onChange)

Combined example:

const Button = ({ variant = 'primary', size = 'md', loading, disabled, className, ...props }) => (
  <button
    data-slot="button"
    data-loading={loading}
    data-disabled={disabled}
    className={cn(buttonVariants({ variant, size }), className)}
    disabled={disabled}
    {...props}
  />
);

// Usage
<Button variant="primary" size="lg">Submit</Button>
<form className="[&_[data-slot=button]]:w-full"><Button>Submit</Button></form>
<Button loading={isLoading} className="data-[loading=true]:opacity-50">Submit</Button>

React Compiler

Context

This project uses React Compiler, which automatically optimizes your React code through automatic memoization at build time. Manual memoization with useMemo, useCallback, and React.memo is rarely needed and often introduces unnecessary complexity.

Core Principle

Write clean, idiomatic React code. Let the compiler optimize it.

React Compiler automatically applies optimal memoization based on data flow analysis. It can even optimize cases that manual memoization cannot handle, such as memoizing values after conditional returns or within complex control flow.

Requirements

DO NOT Use Manual Memoization

NEVER wrap components with React.memo unless you have a specific, documented reason
NEVER use useMemo for performance optimization - the compiler handles this
NEVER use useCallback for performance optimization - the compiler handles this
NEVER create inline functions and then wrap them in useCallback - this is redundant

When Manual Memoization IS Acceptable

Manual memoization should only be used as an escape hatch for precise control in specific scenarios:

Effect Dependencies: When a memoized value is used as a dependency in useEffect to prevent unnecessary effect re-runs
External Library Integration: When passing callbacks to non-React libraries that don't handle reference changes well
Precise Control: When you have profiled and verified that the compiler's automatic memoization is insufficient for a specific hotspot

CRITICAL: If you use manual memoization, you MUST document why with a comment explaining the specific reason.

Examples

Component Memoization

const handleClick = (item) => { onClick(item.id); };

return (

The compiler automatically memoizes components and values, ensuring optimal re-rendering without manual intervention.
</example>

<example type="invalid">
```tsx
// ❌ Avoid - Unnecessary manual memoization
const ExpensiveComponent = memo(function ExpensiveComponent({ data, onClick }) {
  const processedData = useMemo(() => {
    return expensiveProcessing(data);
  }, [data]);

  const handleClick = useCallback((item) => {
    onClick(item.id);
  }, [onClick]);

  return (
    <div>
      {processedData.map(item => (
        <Item key={item.id} onClick={() => handleClick(item)} />
      ))}
    </div>
  );
});

This manual memoization is redundant with React Compiler and adds unnecessary complexity.

Event Handlers

return (

The compiler optimizes this correctly without `useCallback`.
</example>

<example type="invalid">
```tsx
// ❌ Avoid - Unnecessary useCallback
function TodoList({ todos, onToggle }) {
  const handleToggle = useCallback((id) => {
    onToggle(id);
  }, [onToggle]);

  return (
    <ul>
      {todos.map(todo => (
        <TodoItem
          key={todo.id}
          todo={todo}
          onToggle={() => handleToggle(todo.id)}
        />
      ))}
    </ul>
  );
}

The useCallback is unnecessary and creates a subtle bug: the inline arrow function () => handleToggle(todo.id) creates a new function on every render anyway, breaking the memoization.

Computed Values

See Derived State for the pattern. Compute inline during render; React Compiler handles memoization.

Conditional Memoization

// The compiler memoizes this even after the conditional return const mergedTheme = mergeTheme(theme, defaultTheme);

return ( <ThemeContext.Provider value={mergedTheme}> {children} </ThemeContext.Provider> ); }

The compiler can memoize values after conditional returns, which is impossible with manual memoization.
</example>

<example type="invalid">
```tsx
// ❌ Avoid - Attempting manual memoization with early returns
function ThemeProvider({ children, theme }) {
  const mergedTheme = useMemo(
    () => mergeTheme(theme, defaultTheme),
    [theme]
  );

  if (!children) {
    return null;
  }

  return (
    <ThemeContext.Provider value={mergedTheme}>
      {children}
    </ThemeContext.Provider>
  );
}

This forces the expensive merge to run even when returning null, whereas the compiler optimizes this correctly.

Acceptable Use Case: Effect Dependencies

useEffect(() => { fetchData(stableFilters); }, [stableFilters]);

// ... }

This is an acceptable escape hatch with a clear, documented reason.
</example>

### Acceptable Use Case: External Library Integration

<example>
```tsx
// ✅ Acceptable - useCallback for third-party library
function MapComponent({ markers, onMarkerClick }) {
  // Documented reason: GoogleMaps library doesn't handle reference changes well
  // and re-attaches all event listeners on every render
  const handleMarkerClick = useCallback((marker) => {
    onMarkerClick(marker.id);
  }, [onMarkerClick]);

  useEffect(() => {
    markers.forEach(marker => {
      googleMapsApi.addClickListener(marker, handleMarkerClick);
    });
  }, [markers, handleMarkerClick]);

  // ...
}

This is an acceptable escape hatch for external library integration.

Effects

Principle

Treat Effects as an escape hatch for synchronizing React with external systems (DOM APIs, network, imperative libraries). If no external system is involved, keep the logic in render or event handlers.
Rendering must stay pure. Event-driven work (buying, saving, submitting) belongs in the handler that caused it, not in an Effect.
React Compiler assumes idiomatic React semantics. Avoid manual memoization tricks to influence dependency stability; rely on actual values and let the compiler hoist what it can.
For mixing reactive and non-reactive logic, see Separating Events from Effects for useEffectEvent patterns.

When to Add an Effect

Bridging React state to imperative APIs (media playback, map widgets, modals) where you must call imperative methods after paint.
Subscribing to external stores or browser events; prefer useSyncExternalStore when possible so React manages resubscription for you.
Performing work that must run because the component is visible (e.g., logging an analytics impression) with an understanding that it will run twice in development.

When Not to Add an Effect

Deriving or filtering data for rendering. See Derived State.
Resetting or coordinating state between components. Use keys, derive state from props, or lift state up instead of chaining Effects.
Handling user interactions. Run imperative logic inside the event handler so React can batch updates and you avoid double execution.
Preventing Strict Mode double-invocation. Never guard Effects with refs or flags to stop re-execution; fix the underlying cleanup instead.

Derived State: Compute During Render, Not in Effects

The most common unnecessary Effect is transforming data for rendering. When you have data that can be computed from props or state, compute it directly during render:

useEffect(() => { setFiltered(items.filter(item => item.status === filter)); }, [items, filter]);

return ; }

// ✅ Correct: Compute during render function FilteredList({ items, filter }) { const filtered = items.filter(item => item.status === filter); return ; }

</example>

**Why this matters**: The Effect pattern causes an extra render pass with stale data, wastes cycles, and can cause visual flicker.

### When setState in Effect IS Valid

setState in an Effect is valid when the value **comes from an external source** that React can't observe:

1. **DOM measurements** - Reading element dimensions after paint
2. **External subscriptions** - Browser APIs, WebSocket, third-party stores
3. **Resources with cleanup** - Object URLs, media streams, connections

<example>
```tsx
// ✅ Valid: DOM measurement after paint
function Tooltip({ children }) {
  const ref = useRef<HTMLDivElement>(null);
  const [height, setHeight] = useState(0);

  useLayoutEffect(() => {
    if (ref.current) {
      setHeight(ref.current.getBoundingClientRect().height);
    }
  }, []);

  return <div ref={ref}>{children}</div>;
}

// ✅ Valid: External subscription
function OnlineStatus() {
  const [isOnline, setIsOnline] = useState(navigator.onLine);

  useEffect(() => {
    const handler = () => setIsOnline(navigator.onLine);
    window.addEventListener('online', handler);
    window.addEventListener('offline', handler);
    return () => {
      window.removeEventListener('online', handler);
      window.removeEventListener('offline', handler);
    };
  }, []);

  return <span>{isOnline ? 'Online' : 'Offline'}</span>;
}

// ✅ Valid: Resource with cleanup (Object URL)
function ImagePreview({ file }: { file: File }) {
  const objectUrl = useMemo(() => URL.createObjectURL(file), [file]);

  useEffect(() => {
    return () => URL.revokeObjectURL(objectUrl);
  }, [objectUrl]);

  return <img src={objectUrl} alt={file.name} />;
}

Ref Access Rules

Never read or write ref.current during render except for lazy initialization:

// ❌ Invalid: Writing ref during render function Component({ value }) { const ref = useRef(null); ref.current = value; // Don't write during render! return ; }

// ✅ Valid: Read/write in Effects or handlers function Component() { const ref = useRef(null);

useEffect(() => { if (ref.current) { console.log(ref.current.offsetWidth); // OK in effect } }, []);

const handleClick = () => { console.log(ref.current); // OK in handler };

return ; }

// ✅ Valid: Lazy initialization (read-then-write once) function Component() { const ref = useRef<ExpensiveValue | null>(null);

if (ref.current === null) { ref.current = createExpensiveValue(); // OK - one-time init }

return ; }

</example>

### Decision Tree: Derived State vs Effects vs Refs

Need to transform/filter/derive data for display? ├─ YES → Compute during render (no useState, no useEffect) │ const derived = items.filter(x => x.active); │ ├─ Need to cache expensive computation? │ └─ Let React Compiler handle it, or useMemo if profiled bottleneck │ Need to sync with external system (DOM, network, browser API)? ├─ YES → useEffect with setState IS valid │ useEffect(() => { setHeight(ref.current.offsetHeight) }, []) │ Need to read ref.current? ├─ During render → ❌ NEVER (except lazy init) ├─ In Effect → ✅ OK ├─ In handler → ✅ OK │ Need to sync file/blob/stream with cleanup? └─ useMemo for creation + useEffect for cleanup const url = useMemo(() => URL.createObjectURL(file), [file]); useEffect(() => () => URL.revokeObjectURL(url), [url]);


### Red Flags - STOP Before "Fixing"

If you're about to:
- Replace `useState + useEffect` with `useMemo` that reads `ref.current` → STOP
- Add `eslint-disable` for either rule → STOP, use decision tree
- "Fix" one error and immediately get the other → STOP, you're cycling

### Rationalization Table

| Excuse | Reality |
|--------|---------|
| "useMemo fixes derived state" | Only if you don't read refs during render |
| "I'll read ref in useMemo since it runs during render" | useMemo IS render. Ref rules still apply. |
| "Effect was the problem" | Maybe, but check if you're now violating ref rules |
| "This is simple, I know what to do" | The cycle happens because you skip the decision tree |

### Cleanup and Strict Mode

- Always return a cleanup when the Effect allocates resources (connections, listeners, timers). React calls cleanup before re-running the Effect and on unmount.
- Expect every Effect to mount → cleanup → mount in development. Production runs once, but development ensures your Effect is resilient.
- Avoid side-stepping cleanup by storing mutable singletons in refs. This leaves background work running across navigations and breaks invariants.

### React Compiler Considerations

- Because the compiler stabilizes values for you, do not introduce `useMemo`/`useCallback` purely to satisfy Effect dependency linting. Refactor the Effect so it depends on real inputs.
- Let the dependency array express actual inputs. Suppressing ESLint warnings or omitting deps makes compiler output unreliable.
- Prefer custom hooks (`useData`, `useOnlineStatus`) to bundle complex Effect logic once. This keeps call sites simple and lets the compiler optimize the hook body.

<example>
```tsx
// ✅ Effect that syncs with an external API and cleans up
export function VideoPlayer({ src, isPlaying }: Props) {
  const ref = useRef<HTMLVideoElement | null>(null);

useEffect(() => {
const node = ref.current;
if (!node) {
return;
}

    if (isPlaying) {
      void node.play();
    } else {
      node.pause();
    }

    return () => {
      node.pause();
    };

}, [isPlaying]);

return <video ref={ref} src={src} playsInline loop />;
}

useEffect(() => { if (product.isInCart) { setIsInCart(true); // Derivation should happen during render notifyAdd(product.id); // Event logic belongs in the click handler } }, [product]); // ... }


This mixes reactive synchronization with event-driven logic. Use `useEffectEvent` if you need to read current props without re-running the Effect. See [Separating Events from Effects](#separating-events-from-effects).
</example>

<critical>
  - **Derived data**: Compute inline during render. No useState + useEffect.
  - **External systems**: setState in Effect IS valid (DOM, browser APIs, subscriptions).
  - **Refs**: Never read/write during render (except lazy init). Read in Effects/handlers.
  - **Resources with cleanup**: useMemo for creation, useEffect for cleanup.
  - Use Effects only for external synchronization; keep render pure and events in handlers.
  - Always implement cleanup so mount → cleanup → mount cycles behave correctly.
  - Do not fight dependency linting with manual memoization; rely on actual inputs.
</critical>

## Separating Events from Effects

### Principle

Event handlers and Effects serve different purposes in React:

- **Event handlers**: Run in response to specific user interactions. Non-reactive logic.
- **Effects**: Run when synchronization with external systems is needed. Reactive to dependencies.
- **Effect Events** (`useEffectEvent`): Extract non-reactive logic from Effects when you need both behaviors.

### Choosing Between Event Handlers and Effects

Ask: "Does this run because of a specific interaction, or because the component needs to stay synchronized?"

<example>
```tsx
// ✅ Good - Combines both patterns appropriately
function ChatRoom({ roomId }) {
  const [message, setMessage] = useState('');

// Event handler: runs on user click
function handleSendClick() {
sendMessage(message);
}

// Effect: keeps connection synchronized with roomId
useEffect(() => {
const connection = createConnection(serverUrl, roomId);
connection.connect();
return () => connection.disconnect();
}, [roomId]);

return (
<>

<h1>Welcome to the {roomId} room!</h1>
<input value={message} onChange={e => setMessage(e.target.value)} />
<button onClick={handleSendClick}>Send</button>
</>
);
}

Reactive Values and Reactive Logic

Reactive values (props, state, derived values) can change on re-render. Reactive logic responds to these changes:

Event handlers are NOT reactive: Read reactive values but don't re-run when they change
Effects ARE reactive: Must declare reactive values as dependencies and re-run when they change

Extracting Non-Reactive Logic with useEffectEvent

Use useEffectEvent to mix reactive and non-reactive logic:

return Welcome to the {roomId} room!; }

// ✅ With useEffectEvent - Only reconnects on roomId change function ChatRoom({ roomId, theme }) { const onConnected = useEffectEvent(() => { showNotification('Connected!', theme); // Reads current theme, not reactive });

useEffect(() => { const connection = createConnection(serverUrl, roomId); connection.on('connected', onConnected); connection.connect(); return () => connection.disconnect(); }, [roomId]); // ✅ Only roomId

return Welcome to the {roomId} room!; }


</example>

### Reading Latest Props and State with Effect Events

Effect Events always see latest values without causing re-runs. Pass reactive values as arguments for clarity:

<example>
```tsx
// ✅ Common patterns with useEffectEvent

// 1. Page visit logging - Only logs when url changes, not cart
function Page({ url }) {
const { itemCount } = useCart();

const onVisit = useEffectEvent((visitedUrl) => {
logVisit(visitedUrl, itemCount); // Reads latest itemCount
});

useEffect(() => {
onVisit(url); // Pass url as argument for clarity
}, [url]);
}

// 2. Event listener with current state
function useEventListener(emitter, eventName, handler) {
const stableHandler = useEffectEvent(handler);

useEffect(() => {
emitter.on(eventName, stableHandler);
return () => emitter.off(eventName, stableHandler);
}, [emitter, eventName]); // Handler always sees current state
}

// 3. Async operations - Stable trigger value, latest context
function AnalyticsPage({ url }) {
const { itemCount } = useCart();

const onVisit = useEffectEvent((visitedUrl) => {
setTimeout(() => {
logVisit(visitedUrl, itemCount); // visitedUrl: stable, itemCount: latest
}, 5000);
});

useEffect(() => {
onVisit(url);
}, [url]);
}

Critical Rules and Limitations

Never suppress the dependency linter - use useEffectEvent instead:

function handleMove(e) { if (canMove) { // Always sees initial value! setPosition({ x: e.clientX, y: e.clientY }); } }

useEffect(() => { window.addEventListener('pointermove', handleMove); return () => window.removeEventListener('pointermove', handleMove); // eslint-disable-next-line react-hooks/exhaustive-deps }, []); }

// ✅ Use Effect Event instead function Component() { const [canMove, setCanMove] = useState(true);

const onMove = useEffectEvent((e) => { if (canMove) { // Always sees current value setPosition({ x: e.clientX, y: e.clientY }); } });

useEffect(() => { window.addEventListener('pointermove', onMove); return () => window.removeEventListener('pointermove', onMove); }, []); }


</example>

**Effect Event limitations**:

**CRITICAL**: Effect Events can ONLY be called from inside Effects (or other Effect Events). They:

1. **CANNOT be returned from hooks** - ESLint will error if you try to return them
2. **CANNOT be passed to other components or hooks** - ESLint will error if you try to pass them
3. **CANNOT be passed as props** - Props must receive regular functions, not Effect Events
4. **Must be declared locally** where the Effect uses them
5. **Keep close to the Effect** using them

### Pattern: Function Used in Both Props AND Effects

**When a function is needed in BOTH event handlers/props AND useEffect:**

1. Create a regular function for props/event handler use
2. Wrap it in `useEffectEvent` for Effect use only
3. Use the regular function in props, Effect Event in the Effect

<example>
```tsx
// ✅ CORRECT - Dual use: props and Effect
function Component({ editingMessage }) {
  const store = useStore();

// Regular function for props/event handlers
const handleCancelEdit = () => {
store.set('editingMessage', null);
store.set('input', '');
};

// Effect Event wrapper for Effect use
const onCancelEdit = useEffectEvent(handleCancelEdit);

// Effect uses Effect Event version
useEffect(() => {
const handleKeyDown = (e: KeyboardEvent) => {
if (e.key === 'Escape' && editingMessage) {
onCancelEdit(); // Use Effect Event here
}
};

    window.addEventListener('keydown', handleKeyDown);
    return () => window.removeEventListener('keydown', handleKeyDown);

}, [editingMessage]); // No handleCancelEdit in deps!

// Props use regular function
return <Button onClick={handleCancelEdit}>Cancel</Button>;
}

return ; // ESLint error! }

// ❌ WRONG - No Effect Event wrapper causes stale closure function Component({ editingMessage }) { const handleCancelEdit = () => { // Without useCallback, this recreates every render // causing the Effect to re-run constantly };

useEffect(() => { const handleKeyDown = (e: KeyboardEvent) => { if (e.key === 'Escape') { handleCancelEdit(); // Stale closure! } };

window.addEventListener('keydown', handleKeyDown);
return () => window.removeEventListener('keydown', handleKeyDown);

}, [handleCancelEdit]); // Effect re-runs every render! }


</example>

<example>
```tsx
// ❌ WRONG - Cannot return Effect Events from hooks
function useTimer(callback, delay) {
  const onTick = useEffectEvent(callback);

useEffect(() => {
const id = setInterval(onTick, delay);
return () => clearInterval(id);
}, [delay]);

return onTick; // ❌ ESLint error: Effect Events cannot be returned
}

// ❌ WRONG - Cannot pass Effect Events to components
function Timer() {
const onTick = useEffectEvent(() => setCount(count + 1));
return <CustomTimer onTick={onTick} />; // ❌ ESLint error: Effect Events cannot be passed
}

// ✅ CORRECT - Effect Events only used inside Effects
function useTimer(callback, delay) {
const onTick = useEffectEvent(callback);

useEffect(() => {
const id = setInterval(onTick, delay);
return () => clearInterval(id);
}, [delay]);
// No return - Effect Event stays internal
}

// ✅ CORRECT - Return regular function, use Effect Event internally
function useScrollCheck(target, enabled) {
const canCheck = useDebounce(enabled, 100);

// Regular function for external use
const scrollCheck = () => {
if (!canCheck || !target) return;
// ... scroll check logic
};

// Effect Event wrapper for internal Effect use
const onScrollCheck = useEffectEvent(scrollCheck);

useEffect(() => {
onScrollCheck(); // Call Effect Event inside Effect
}, [canCheck, target]);

return { scrollCheck }; // Return regular function, not Effect Event
}

Common Patterns

Lists and Iteration

    return (
      <ProductCard
        key={product.id}
        product={product}
        finalPrice={discountedPrice}
        onAddToCart={() => onAddToCart(product.id)}
      />
    );
  })}
</div>

); }


The compiler optimizes this correctly, including the computed `discountedPrice`.
</example>

### Derived State

See [Derived State: Compute During Render](#derived-state-compute-during-render-not-in-effects) in the Effects section.

## Migration Guide

### Removing Existing Memoization

If you're working with existing code that has manual memoization:

1. **Remove it** - React Compiler handles optimization automatically
2. **Test thoroughly** - Verify functionality after removal
3. **Trust the compiler** - It applies optimal memoization based on data flow analysis
4. **Only keep if documented** - Manual memoization should only remain for the specific escape hatch scenarios documented above

The compiler's output is designed to work with clean, idiomatic React code. Removing manual memoization improves readability and lets the compiler do its job correctly.

### Adding New Code

Write clean, idiomatic React without manual memoization. See [DO NOT Use Manual Memoization](#do-not-use-manual-memoization) for details.