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
.claude/rules/advanced-event-handler-refs.mdWhat 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.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/advanced-event-handler-refs.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/advanced-event-handler-refs.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/advanced-event-handler-refs.mdManually: put the files in place
.clinerules/advanced-event-handler-refs.mdStep 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