(번역) 리액트의 useEffectEvent 이해하기: 오래된 클로저 해결을 위한 완벽 가이드

 

원문: Understanding React’s useEffectEvent: A Complete Guide to Solving Stale Closures

 

TL;DR

useEffectEvent를 사용하면 의존성 배열에 추가하지 않고도 Effect 내부에서 최신 props나 상태를 읽을 수 있습니다. 이렇게 하면 해당 값이 변경되어도 Effect가 다시 실행되지 않습니다. 첫 번째 예제로 이동하기.

 

핵심 문제(The Core Problem)

상황은 이렇습니다. WebSocket 연결, 간격 타이머, 구독과 같이 비용이 많이 드는 작업을 설정하는 useEffect가 있습니다. 그 설정 내부에서 콜백이 어떤 상태값을 읽어야 합니다. 하지만 그 상태값이 변경될 때마다 연결을 끊고 다시 설정하고 싶지는 않을 것입니다.

갈등 요소는 다음과 같습니다.

 

• 상태값을 의존성 배열에 포함하면 → Effect가 다시 실행되고 연결이 재시작됩니다(나쁨).
• 상태값을 의존성 배열에서 제외하면 → 콜백이 오래된 값을 보게 됩니다(역시 나쁨).

useEffectEvent가 이 문제를 해결합니다. 이것은 호출될 때 항상 최신 값을 읽지만 반응형 의존성으로 취급되지 않는 함수를 제공합니다.

 

예제 1: 채팅방 연결

채팅 컴포넌트를 만들어보겠습니다. 메시지가 도착하면 소리를 재생하려고 합니다. 단, 사용자가 알림을 음소거하지 않았을 때만 소리를 재생해야 합니다.

잘못된 버전 (오래된 클로저)

import { useEffect, useState } from "react";

function ChatRoom({ roomId }: { roomId: string }) {
  const [isMuted, setIsMuted] = useState(false);

  useEffect(() => {
    const connection = connectToRoom(roomId);

    connection.on("message", (message: string) => {
      // 버그: 이것은 isMuted의 초기 값을 캡처합니다
      // 사용자가 체크박스를 토글할 때 업데이트된 값을 알 수 없을 것입니다!
      if (!isMuted) {
        playSound();
      }
    });

    return () => connection.disconnect();
  }, [roomId]); // ❌ isMuted가 누락됨 - 콜백이 오래된 값을 봅니다!

  return (
    <div>
      <h1>Chat Room: {roomId}</h1>
      <label>
        <input
          type="checkbox"
          checked={isMuted}
          onChange={(e) => setIsMuted(e.target.checked)}
        />
        Mute notifications
      </label>
    </div>
  );
}

 

무엇이 잘못되었을까요? 콜백은 Effect가 처음 실행될 때 isMuted를 캡처합니다. 사용자가 음소거를 토글했나요? 콜백은 여전히 이전 값을 보고 있습니다. 클로저(closure)가 오래된 상태인 것입니다.

 

새로운 문제를 만드는 "해결책"

"그냥 isMuted를 의존성 배열에 추가하면 되잖아!"라고 생각할 수도 있습니다.

useEffect(() => {
  const connection = connectToRoom(roomId);

  connection.on("message", (message: string) => {
    if (!isMuted) {
      playSound();
    }
  });

  return () => connection.disconnect();
}, [roomId, isMuted]); // ❌ 이제 isMuted가 재연결을 트리거합니다!

 

이제 콜백은 최신 값을 봅니다... 하지만 isMuted가 변경될 때마다,

 

1. 리액트가 클린업 함수를 실행 → connection.disconnect()
2. 리액트가 Effect를 다시 실행 → connectToRoom(roomId)
3. 새로운 메시지 핸들러가 등록됨

음소거 체크박스를 토글하면 채팅이 다시 연결됩니다! 재연결 중에 메시지를 놓칠 수도 있습니다. 서버는 연결이 자주 끊겼다 붙었다 하는 것을 보게 됩니다. 이는 낭비이고 고장난 것입니다.

 

해결책: useEffectEvent

import { useEffect, useState, useEffectEvent } from "react";

function ChatRoom({ roomId }: { roomId: string }) {
  const [isMuted, setIsMuted] = useState(false);

  // Effect Event 생성 - 호출될 때 최신 isMuted를 읽음
  const onMessage = useEffectEvent((message: string) => {
    if (!isMuted) {
      playSound();
    }
  });

  useEffect(() => {
    const connection = connectToRoom(roomId);
    connection.on("message", onMessage);
    return () => connection.disconnect();
  }, [roomId]); // ✅ roomId만 재연결을 트리거함

  return (
    <div>
      <h1>Chat Room: {roomId}</h1>
      <label>
        <input
          type="checkbox"
          checked={isMuted}
          onChange={(e) => setIsMuted(e.target.checked)}
        />
        Mute notifications
      </label>
    </div>
  );
}

 

이제 어떤 일이 일어날까요?

 

• roomId 변경 → 재연결 (정상!)
• isMuted 토글 → 연결에 아무런 영향 없음
• 메시지 도착 → onMessage가 현재 isMuted 값을 확인

Effect는 오직 roomId에만 관심을 가집니다. onMessage 함수는 호출될 때 isMuted를 읽어, 그 순간의 현재 값을 가져옵니다.

 

예제 2: REST 폴링 대시보드

또 다른 흔한 시나리오는 10초마다 API를 폴링(polling)하는 대시보드입니다. 요청에는 사용자가 토글할 수 있는 필터 옵션이 포함됩니다.

 

잘못된 버전 (타이머 리셋)

import { useEffect, useState } from "react";

function Dashboard({ teamId }: { teamId: string }) {
  const [includeArchived, setIncludeArchived] = useState(false);
  const [data, setData] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      const response = await fetch(
        `/api/team/${teamId}/tasks?archived=${includeArchived}`
      );
      const json = await response.json();
      setData(json);
    };

    fetchData(); // 즉시 가져오기
    const intervalId = setInterval(fetchData, 10000); // 그 후 매 10초마다

    return () => clearInterval(intervalId);
  }, [teamId, includeArchived]); // ❌ 체크박스 토글 시 타이머가 재시작됩니다!

  return (
    <div>
      <h1>Team Dashboard</h1>
      <label>
        <input
          type="checkbox"
          checked={includeArchived}
          onChange={(e) => setIncludeArchived(e.target.checked)}
        />
        Include archived tasks
      </label>
      <ul>
        {data?.map((task) => (
          <li key={task.id}>{task.name}</li>
        ))}
      </ul>
    </div>
  );
}

 

무엇이 잘못되었을까요? 사용자가 "보관된 작업 포함(Include archived)"을 토글할 때마다,

 

1. Effect 클린업 실행 → clearInterval(intervalId)
2. Effect 다시 실행 → 새로운 간격(interval)이 0부터 시작

사용자가 3초 안에 5번 토글하면, 타이머는 5번 리셋되고 실제로 실행되지 않습니다. 클릭을 멈출 때까지 데이터는 가져와지지 않습니다.

 

해결책: useEffectEvent

import { useEffect, useState, useEffectEvent } from "react";

function Dashboard({ teamId }: { teamId: string }) {
  const [includeArchived, setIncludeArchived] = useState(false);
  const [data, setData] = useState(null);

  // Effect Event가 호출될 때 최신 includeArchived를 읽음
  const fetchData = useEffectEvent(async () => {
    const response = await fetch(
      `/api/team/${teamId}/tasks?archived=${includeArchived}`
    );
    const json = await response.json();
    setData(json);
  });

  useEffect(() => {
    fetchData();
    const intervalId = setInterval(fetchData, 10000);
    return () => clearInterval(intervalId);
  }, [teamId]); // ✅ teamId만 간격을 재시작함

  return (
    <div>
      <h1>Team Dashboard</h1>
      <label>
        <input
          type="checkbox"
          checked={includeArchived}
          onChange={(e) => setIncludeArchived(e.target.checked)}
        />
        Include archived tasks
      </label>
      <ul>
        {data?.map((task) => (
          <li key={task.id}>{task.name}</li>
        ))}
      </ul>
    </div>
  );
}

 

이제 어떤 일이 일어날까요?

 

• teamId 변경 → 간격 재시작, 새로운 팀 데이터 가져오기 (정상!)
• "보관된 작업 포함" 토글 → 간격이 중단 없이 계속 실행됨
• 다음 fetch → 현재 includeArchived 값을 사용

 

기존의 임시 해결책: useRef

useEffectEvent 이전에는 값을 useRef에 미러링하는 것이 표준 패턴이었습니다.

import { useEffect, useLayoutEffect, useState, useRef } from "react";

function Dashboard({ teamId }: { teamId: string }) {
  const [includeArchived, setIncludeArchived] = useState(false);
  const [data, setData] = useState(null);

  // 1단계: ref 생성
  const includeArchivedRef = useRef(includeArchived);

  // 2단계: useLayoutEffect를 사용하여 ref를 state와 동기화 유지
  // 이는 useEffect 이전에 동기적으로 실행되어 ref가 최신임을 보장함
  useLayoutEffect(() => {
    includeArchivedRef.current = includeArchived;
  }, [includeArchived]);

  // 3단계: Effect에서 ref 읽기
  useEffect(() => {
    const fetchData = async () => {
      const response = await fetch(
        `/api/team/${teamId}/tasks?archived=${includeArchivedRef.current}`
      );
      const json = await response.json();
      setData(json);
    };

    fetchData();
    const intervalId = setInterval(fetchData, 10000);

    return () => clearInterval(intervalId);
  }, [teamId]);

  // ... JSX
}

 

왜 useEffect 대신 useLayoutEffect를 사용할까요?

 

"그냥 두 개의 useEffect 훅을 순서대로 사용하면 안 되나요? 첫 번째는 ref를 동기화하고, 두 번째는 그것을 읽는 식으로요."라고 궁금해할 수 있습니다.

 

실제로는 이는 종종 제대로 작동합니다. 리액트는 일반적으로 선언된 순서대로 effect를 실행합니다. 하지만 함정은 여기에 있습니다. 리액트 문서에 의하면 여러 useEffect 훅 간의 실행 순서를 명시적으로 보장하지 않습니다. 문서는 effect가 컴포넌트가 커밋된 후에 실행된다고 명시하지만, 여러 effect 간의 정확한 순서—특히 동시 렌더링, Suspense 경계 또는 미래의 리액트 버전—는 리액트의 공개 API 기능이 아닙니다.

 

useLayoutEffect는 명시적인 보장을 제공합니다. 리액트 문서에 따르면,

"useLayoutEffect는 브라우저가 화면을 다시 그리기 전에 실행되는 useEffect의 버전입니다."

"리액트는 useLayoutEffect 내부의 코드와 그 안에서 예약된 모든 상태 업데이트가 브라우저가 화면을 다시 그리기 전에 처리됨을 보장합니다."

 

이는 실행 순서가 잘 정의되어 있음을 의미합니다.

 

1. 컴포넌트 렌더링
2. 리액트가 변경 사항을 DOM에 커밋
3. useLayoutEffect가 동기적으로 실행됨 → ref가 동기화됨
4. 브라우저가 화면을 그림
5. useEffect 실행 → 이미 업데이트된 ref를 읽음

 

동기화에 useLayoutEffect를 사용함으로써, 관찰되었지만 명시되지 않은 구현 세부 사항이 아닌 문서화되고 보장된 동작에 의존하게 됩니다.

 

이 패턴의 단점은 다음과 같습니다.

 

• 추가적인 useRef 선언
• 동기화를 유지하기 위한 추가적인 useLayoutEffect
• 상태값을 직접 읽는 것이 아니라 .current를 읽어야 함을 기억해야 함
• "제외(escape)"시켜야 하는 모든 값에 대해 반복해야 함
• 실수로 useEffect를 사용하기 쉬움 (작동할 수도 있지만... 언젠가 멈출 때까지)

 

useEffectEvent는 바로 이 패턴을 자동화하고 이러한 실수의 가능성을 제거합니다.

 

함수 동일성에 대한 참고 사항

⚠️ 흔한 혼란: 반환된 함수는 안정적인가요?

onMessage(useEffectEvent가 반환하는 함수)는 안정적일지 궁금할 수 있습니다. useCallback이 제공하는 것처럼 렌더링할 때마다 동일한 참조일까요?

아니요, 그리고 그건 중요하지 않습니다.

리액트는 매 렌더링마다 새로운 onMessage 함수를 반환합니다. 만약 onMessage를 의존성 배열에 넣으면, Effect는 매 렌더링마다 다시 실행될 것입니다. 이는 잘못 사용하고 있다는 신호입니다.

여전히 작동하는 이유: 모든 버전의 onMessage (렌더링 1, 렌더링 2 등에서의)는 동일한 내부 ref를 읽습니다. 리액트는 그 ref를 계속 업데이트합니다. 따라서 구독이 렌더링 1에서 캡처한 onMessage를 호출하더라도, 여전히 현재 값을 가진 최신 콜백을 읽게 됩니다.

결론: 안정성에 대해 걱정하지 마세요. 규칙만 따르세요. Effect 내부에서 호출하고, 절대로 의존성으로 나열하지 마세요.

 

내부 작동 원리

마법은 없습니다. useEffectEvent는 여러분이 useRef로 하던 일을 정확히 수행하지만, 리액트가 대신 처리해줍니다.

개념적 모델은 다음과 같습니다(실제 리액트 구현은 아님).

function useEffectEvent<T extends (...args: any[]) => any>(callback: T): T {
  const latestCallbackRef = useRef(callback)

  // 리액트는 실제로 렌더링이 아닌 커밋 단계에서 이를 업데이트합니다
  // (명확성을 위해 여기서 단순화됨)
  latestCallbackRef.current = callback

  // 매 렌더링마다 새로운 함수를 반환 - 의도적임!
  // 모든 버전이 동일한 ref를 읽으므로 모두 최신 값을 얻음
  return ((...args: Parameters<T>) => {
    return latestCallbackRef.current(...args)
  }) as T
}

 

핵심 통찰: 모든 함수 인스턴스는 동일한 ref를 공유합니다. Effect가 렌더링 1에서 "오래된" 함수를 캡처했더라도, 이를 호출하면 latestCallbackRef.current를 읽게 되며, 이는 최신 콜백을 가리킵니다.

 

오래된 클로저 문제 시각화

 

useRef가 이 문제를 해결하는 방법

 

useEffectEvent가 이 문제를 해결하는 방법

 

동등성

 

규칙 및 주의사항

useEffectEvent에는 중요한 규칙들이 있습니다. eslint-plugin-react-hooks (버전 6.1.1 이상)가 이를 강제합니다.

 

규칙 1: Effect 내부에서만 Effect Event를 호출하세요

Effect Event는 단 하나의 목적을 위해 설계되었습니다. Effect 내부에서 호출되는 것입니다.

// ✅ 올바름: Effect 내부에서 호출됨
const onMessage = useEffectEvent((msg: string) => {
  console.log(msg, latestState);
});

useEffect(() => {
  socket.on("message", onMessage);
  return () => socket.off("message", onMessage);
}, []);

// ❌ 잘못됨: 이벤트 핸들러에서 호출됨
<button onClick={() => onMessage("hello")}>Click me</button>;

// ❌ 잘못됨: 렌더링 중에 호출됨
return <div>{onMessage("rendered")}</div>;

 

리액트는 이를 적극적으로 막습니다. Effect 컨텍스트 밖에서 Effect Event를 호출하면 에러를 발생시킵니다.

일반적인 이벤트 핸들러(onClick, onChange 등)의 경우 useEffectEvent가 필요하지 않습니다. 그러한 핸들러는 각 상호작용(interaction)마다 현재 값으로 새로 실행됩니다.

 

규칙 2: 다른 컴포넌트에 Effect Event를 전달하지 마세요

Effect Event를 해당 컴포넌트 내부에 유지하세요.

// ❌ 잘못됨: Effect Event를 prop으로 전달
function Parent() {
  const onTick = useEffectEvent(() => {
    console.log(latestCount)
  })
  return <Timer onTick={onTick} /> // 이렇게 하지 마세요!
}

// ✅ 올바름: Effect Event를 로컬로 유지
function Parent() {
  const [count, setCount] = useState(0)
  const onTick = useEffectEvent(() => {
    console.log(count)
  })

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

  return <div>Count: {count}</div>
}

 

규칙 3: 린터 경고를 피하기 위해 useEffectEvent를 사용하지 마세요

이것은 의도에 관한 문제입니다. "이 값이 변경될 때, Effect가 다시 실행되어야 하는가?" 스스로에게 물어보세요.

 

• 예 → 의존성입니다. 의존성 배열에 추가하세요.
• 아니요 → 로직을 Effect Event로 감싸세요.

// ❌ 잘못됨: page를 의존성으로 나열하는 것을 피하기 위해 useEffectEvent 사용
const fetchData = useEffectEvent(async () => {
  const data = await fetch(`/api/items?page=${page}`)
  setItems(data)
})

useEffect(() => {
  fetchData()
}, []) // "이제 deps에 page가 필요 없어!" <- 잘못된 생각!

// ✅ 올바름: page는 의존성이어야 함 - 변경될 때 다시 가져오기를 원함
useEffect(() => {
  async function fetchData() {
    const data = await fetch(`/api/items?page=${page}`)
    setItems(data)
  }
  fetchData()
}, [page])

 

언제 useEffectEvent를 사용해야 할까요?

Effect 내부에 다음과 같은 콜백이 있을 때 사용하세요.

 

1. 재등록하고 싶지 않은 구독, 타이머, 또는 외부 라이브러리에 전달됨
2. 호출될 때 최신 props/state를 읽어야 함
3. 그러한 값들이 Effect의 재실행을 트리거하지 않아야 함

 

상황	반응형 (Effect 실행 유발)	비반응형 (Effect Event)
채팅방 연결	roomId	isMuted, theme
폴링 대시보드	teamId	includeArchived, sortOrder
분석 로깅	pageUrl	cartItemCount, userId
웹소켓 메시지	socketUrl	isOnline, preferences
간격 타이머	- (한 번만 실행됨)	count, step

 

리액트 버전 참고 사항

useEffectEvent는 리액트 19.2에서 안정적인 기능으로 도입되었습니다. 이전 버전을 사용 중이라면,

 

• 리액트 18.x 및 이전: 위에서 설명한 useRef 패턴을 사용하세요.
• 리액트 19.0-19.1: useEffectEvent를 사용할 수 있었지만 실험적이었습니다.
• 리액트 19.2+: 자신 있게 useEffectEvent를 사용하세요.

사용 중인 리액트 버전을 다음 명령어로 확인하세요.

npm list react

 

요약

useEffectEvent는 하나의 특정 문제를 해결합니다. Effect 콜백 내에서 최신 값을 읽으면서도, 그 값들이 Effect를 다시 실행시키지 않도록 하는 것입니다.

 

그게 전부입니다. 다른 마법은 없습니다.

 

멘탈 모델:

• 의존성의 대답: "이 Effect는 언제 다시 실행되어야 하는가?"
• Effect Event의 대답: "Effect의 콜백이 실행될 때 어떤 값을 읽어야 하는가?"

이러한 관심사를 분리함으로써 코드는 더 명확해지고 버그가 발생할 여지가 줄어듭니다.

 

추가 읽을거리

• React Docs: useEffectEvent Reference - 공식 API 문서
• React Docs: Separating Events from Effects - 심층적인 개념 가이드
• React Docs: useEffect Reference - 포괄적인 Effect 문서
• MDN: Closures - 오래된 클로저(Stale Closures)의 배경이 되는 자바스크립트 개념 이해하기