[react 번역] captureOwnerStack

출처: https://react.dev/reference/react/captureOwnerStack

---

개요

captureOwnerStack은 개발 환경에서 현재 React Owner Stack(오너 스택)을 문자열로 읽어오는 API입니다. 주로 커스텀 에러 오버레이 등에서, 에러가 발생한 컴포넌트의 소유자 트리(Owner Stack)를 확인할 때 사용합니다.

const stack = captureOwnerStack();

---

Reference

captureOwnerStack()

현재 Owner Stack을 문자열로 반환합니다. 개발 환경에서만 동작하며, 프로덕션에서는 항상 null을 반환합니다.

• 파라미터: 없음
• 반환값: string | null (Owner Stack 문자열 또는 null)

Owner Stack이 제공되는 위치

• 컴포넌트 렌더링 중
• Effect(예: useEffect) 내부
• React 이벤트 핸들러(예: <button onClick={...} />)
• React 에러 핸들러(onCaughtError, onRecoverableError, onUncaughtError 등)

Owner Stack이 없는 경우(예: setTimeout, fetch, 커스텀 DOM 이벤트 등 React 컨트롤 외부)에는 null이 반환됩니다.

Caveats(주의사항)

• 개발 환경에서만 동작합니다. 프로덕션 번들에서는 항상 null 또는 undefined입니다.
• 프로덕션/개발 번들 모두에서 안전하게 사용하려면 네임스페이스 import 후 조건부로 접근하세요.

---

Owner Stack vs Component Stack

• Owner Stack: 해당 노드를 "생성"한 컴포넌트의 트리만 포함합니다. 단순히 children을 전달한 부모(App 등)나 DOM 요소는 포함되지 않습니다.
• Component Stack: 에러 핸들러 등에서 제공되는 전체 컴포넌트 트리입니다.

예시:

• Component Stack: at SubComponent → at fieldset → at Component → at main → at React.Suspense → at App
• Owner Stack: at Component (실제로 SubComponent를 생성한 컴포넌트만)

---

사용법

현재 Owner Stack 읽기

import * as React from 'react';

function MyComponent() {
  if (process.env.NODE_ENV !== 'production') {
    const ownerStack = React.captureOwnerStack();
    console.log(ownerStack);
  }
}

커스텀 에러 오버레이에 활용

import { captureOwnerStack } from 'react';

const originalConsoleError = console.error;
console.error = function patchedConsoleError(...args) {
  originalConsoleError.apply(console, args);
  const ownerStack = captureOwnerStack();
  // 에러 오버레이 등에 ownerStack 활용
  onConsoleError({
    consoleMessage: args[0],
    ownerStack,
  });
};

---

트러블슈팅

Owner Stack이 null인 경우

• React가 관리하지 않는 컨텍스트(예: setTimeout, fetch, 커스텀 DOM 이벤트 등)에서 호출하면 null이 반환됩니다.
• 반드시 렌더, Effect, React 이벤트 핸들러, React 에러 핸들러 등 React 컨트롤 내에서 호출해야 합니다.

captureOwnerStack이 undefined인 경우

• 프로덕션 번들에서는 이 API가 export되지 않으므로 undefined입니다.
• 개발/프로덕션 번들 모두에서 안전하게 사용하려면 네임스페이스 import 후 조건부로 접근하세요.

import * as React from 'react';
if (process.env.NODE_ENV !== 'production') {
  const ownerStack = React.captureOwnerStack?.();
  console.log('Owner Stack', ownerStack);
}

---

출처: https://react.dev/reference/react/captureOwnerStack