useDebugValue
소개
useDebugValue는 React DevTools에서 커스텀 Hook에 라벨을 추가할 수 있게 해주는 React Hook이에요.
useDebugValue(value, format?)목차
레퍼런스
useDebugValue(value, format?)
커스텀 Hook의 최상위 레벨에서 useDebugValue를 호출하면 읽기 쉬운 디버그 값을 표시할 수 있어요:
import { useDebugValue } from 'react';
function useOnlineStatus() {
// ...
useDebugValue(isOnline ? 'Online' : 'Offline');
// ...
}매개변수
value: React DevTools에 표시하고 싶은 값이에요. 어떤 타입이든 상관없어요.- 선택적
format: 포맷팅 함수예요. 컴포넌트를 검사(inspect)할 때, React DevTools가value를 인자로 넘겨서 이 포맷팅 함수를 호출하고, 반환된 포맷팅된 값을 표시해요 (반환값도 어떤 타입이든 가능해요). 포맷팅 함수를 지정하지 않으면, 원래의value자체가 그대로 표시돼요.
반환값
useDebugValue는 아무것도 반환하지 않아요.
사용법
커스텀 Hook에 라벨 추가하기
커스텀 Hook의 최상위 레벨에서 useDebugValue를 호출하면 React DevTools에 읽기 쉬운 디버그 값을 표시할 수 있어요.
import { useDebugValue } from 'react';
function useOnlineStatus() {
// ...
useDebugValue(isOnline ? 'Online' : 'Offline');
// ...
}이렇게 하면 useOnlineStatus를 호출하는 컴포넌트를 검사할 때 OnlineStatus: "Online" 같은 라벨이 표시돼요:
useDebugValue 호출이 없으면, 기본 데이터(이 예제에서는 true)만 표시될 거예요.
즉,
useDebugValue를 사용하면 DevTools에서 단순히true/false같은 원시값 대신"Online","Offline"같이 사람이 읽기 쉬운 의미 있는 라벨을 보여줄 수 있다는 뜻이에요.
// App.js
import { useOnlineStatus } from './useOnlineStatus.js';
function StatusBar() {
const isOnline = useOnlineStatus();
return <h1>{isOnline ? '✅ Online' : '❌ Disconnected'}</h1>;
}
export default function App() {
return <StatusBar />;
}// src/useOnlineStatus.js
import { useSyncExternalStore, useDebugValue } from 'react';
export function useOnlineStatus() {
const isOnline = useSyncExternalStore(subscribe, () => navigator.onLine, () => true);
useDebugValue(isOnline ? 'Online' : 'Offline');
return isOnline;
}
function subscribe(callback) {
window.addEventListener('online', callback);
window.addEventListener('offline', callback);
return () => {
window.removeEventListener('online', callback);
window.removeEventListener('offline', callback);
};
}참고
모든 커스텀 Hook에 디버그 값을 추가하지 마세요. 공유 라이브러리의 일부이면서 내부 데이터 구조가 복잡해서 검사하기 어려운 커스텀 Hook에 사용할 때 가장 유용해요.
다시 말해서, 간단한 커스텀 Hook이라면 굳이
useDebugValue를 넣을 필요가 없어요. 복잡한 로직을 가진 Hook이거나, 여러 사람이 사용하는 라이브러리용 Hook에서 디버깅을 편하게 하려고 쓰는 게 좋다는 뜻이에요.
디버그 값의 포맷팅 지연시키기
useDebugValue의 두 번째 인자로 포맷팅 함수를 전달할 수도 있어요:
useDebugValue(date, date => date.toDateString());포맷팅 함수는 디버그 값을 매개변수로 받고, 포맷팅된 표시 값을 반환해야 해요. 컴포넌트를 검사할 때 React DevTools가 이 함수를 호출하고 그 결과를 표시해줘요.
이렇게 하면 컴포넌트가 실제로 검사될 때만 잠재적으로 비용이 큰 포맷팅 로직을 실행할 수 있어요. 예를 들어, date가 Date 값이라면, 매 렌더링마다 toDateString()을 호출하는 걸 피할 수 있죠.
보충 설명을 하자면, 만약 포맷팅 함수 없이
useDebugValue(date.toDateString())처럼 직접 포맷팅한 값을 넘기면, 컴포넌트가 렌더링될 때마다toDateString()이 호출돼요. DevTools를 열어서 검사하지 않더라도요. 하지만 두 번째 인자로 포맷팅 함수를 넘기면, DevTools에서 실제로 해당 컴포넌트를 검사할 때만 포맷팅 함수가 실행되기 때문에 불필요한 연산을 줄일 수 있어요. 이게 바로 "포맷팅을 지연시킨다"는 의미예요.
