Skip to main content
rule CX Codex

advanced-event-handler-refs — Claude Code rule: setup & use

advanced-event-handler-refs guides Claude Code to keep event callbacks in refs or useEffectEvent, stopping React effects from re-subscribing on every render.

MIT ★ 7,191 updated 2026-10-24

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/advanced-event-handler-refs.md
Open on GitHub

What advanced-event-handler-refs does

The rule enforces a React pattern for effect dependencies. Passing raw callbacks into a useEffect dependency array tears down and re-attaches listeners whenever the parent component updates.

Instead, Claude Code stores the callback in a useRef container and syncs it separately, or turns to useEffectEvent when available. The actual subscription depends only on event identifiers, calling ref.current during execution.

The useEffectEvent alternative requires a recent React release that supports the hook.

What it helps with

  • stop window event listeners from re-subscribing on every render
  • keep hook dependency arrays stable when handling callbacks
  • implement useEffectEvent for cleaner event subscription hooks

Example prompts for the agent

  • Write a useWindowEvent hook that listens to keyboard events without re-subscribing
  • Refactor this effect to use handlerRef instead of putting the callback in dependencies

How to install advanced-event-handler-refs

Manually: put the files in place

.claude/rules/advanced-event-handler-refs.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about advanced-event-handler-refs

How do I install advanced-event-handler-refs in Claude Code?

Save the rule file to .claude/rules/advanced-event-handler-refs.md in your project root.

What does advanced-event-handler-refs do?

It instructs the assistant to store event handlers in refs inside React hooks. This prevents effects from resetting subscriptions whenever callback references change.

When should I use useEffectEvent instead of useRef?

Use useEffectEvent if your project runs on a newer React version with support for it. It creates a stable function reference without manual ref synchronization.

Source text

advanced-event-handler-refs.md · MIT
---
title: Store Event Handlers in Refs
impact: LOW
impactDescription: stable subscriptions
tags: advanced, hooks, refs, event-handlers, optimization
---

## Store Event Handlers in Refs

Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.

**Incorrect (re-subscribes on every render):**

```tsx
function useWindowEvent(event: string, handler: (e) => void) {
  useEffect(() => {
    window.addEventListener(event, handler)
    return () => window.removeEventListener(event, handler)
  }, [event, handler])
}
```

**Correct (stable subscription):**

```tsx
function useWindowEvent(event: string, handler: (e) => void) {
  const handlerRef = useRef(handler)
  useEffect(() => {
    handlerRef.current = handler
  }, [handler])

  useEffect(() => {
    const listener = (e) => handlerRef.current(e)
    window.addEventListener(event, listener)
    return () => window.removeEventListener(event, listener)
  }, [event])
}
```

**Alternative: use `useEffectEvent` if you're on latest React:**

```tsx
import { useEffectEvent } from 'react'

function useWindowEvent(event: string, handler: (e) => void) {
  const onEvent = useEffectEvent(handler)

  useEffect(() => {
    window.addEventListener(event, onEvent)
    return () => window.removeEventListener(event, onEvent)
  }, [event])
}
```

`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.

© tech-leads-club · MIT · tech-leads-club/agent-skills

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set130

The whole set →
rerender-derived-state-no-effect The rerender-derived-state-no-effect rule keeps derived values out of React state and avoids effects that mirror props. Use it when reviewing components for extra renders and state drift. CX Codex +1 ★ 7,191repo stars rerender-move-effect-to-event rerender-move-effect-to-event tells the agent to fire a side effect from the handler that caused it, not from useEffect watching a state flag. CX Codex +1 ★ 7,191repo stars async-dependencies async-dependencies instructs Claude Code to execute partially dependent async tasks concurrently using better-all or native promise chains rather than blocking Promise.all calls. CX Codex +1 ★ 7,191repo stars server-cache-lru The server-cache-lru rule explains when React.cache() is too narrow and an LRU cache should share data between requests. Use it for sequential actions that reuse the same records. CX Codex +1 ★ 7,191repo stars server-parallel-fetching The server-parallel-fetching rule shows how to compose React Server Components so independent data requests can run in parallel. Use it when one component waits on another component’s fetch. CX Codex +1 ★ 7,191repo stars _sections Defines eight performance optimization sections, ranks them by impact, and guides the agent in prioritizing code improvements. Install once, reference by ID when analyzing bottlenecks. CX Codex +1 ★ 7,191repo stars client-passive-event-listeners client-passive-event-listeners instructs the agent to add { passive: true } to touch and wheel listeners, preventing scroll stutter in browser viewports. CX Codex +1 ★ 7,191repo stars js-cache-storage js-cache-storage keeps localStorage, sessionStorage and cookie values in memory so reads stop hitting synchronous browser storage. CX Codex +1 ★ 7,191repo stars

Project sponsors

Companies that keep this analytics open