Watchman은 React Native 개발에서 왜 필요할까

React Native나 Expo로 개발하다 보면 코드를 고쳤는데 앱에 바로 반영되지 않는 경우가 있습니다. 이때 원인 중 하나가 파일 변경 감시 도구인 Watchman 문제일 수 있습니다.

Watchman이란

Watchman은 Meta가 만든 파일 시스템 변경 감시 도구입니다. 프로젝트 안의 파일이 바뀌면 이를 빠르게 감지해 Metro 같은 도구에 알려줍니다.

대규모 프로젝트에서는 파일이 많기 때문에 단순 폴링 방식보다 전문 감시 도구가 더 안정적입니다.

Metro와 Fast Refresh

React Native의 Metro 번들러는 소스 코드 변경을 감지해 앱에 빠르게 반영합니다. 이 기능이 Fast Refresh입니다.

Watchman이 정상 동작하면 파일 변경이 빠르게 감지되고, 앱 화면도 자연스럽게 갱신됩니다.

문제가 생기면 나타나는 증상

Watchman이나 Metro 캐시가 꼬이면 다음 증상이 나타날 수 있습니다.

• 파일을 저장해도 앱이 갱신되지 않는다.
• 예전 코드가 계속 실행된다.
• Metro를 재시작해야만 변경이 반영된다.
• 특정 파일 변경만 감지되지 않는다.

기본 해결 방법

먼저 Metro 캐시를 비우고 다시 시작해 볼 수 있습니다.

npx expo start -c

Watchman 상태가 문제라면 watch를 초기화하는 방법도 있습니다.

watchman watch-del-all

환경에 따라 Watchman을 재설치하거나 업데이트해야 할 수도 있습니다.

실무 팁

• 프로젝트가 커질수록 Watchman 설치를 권장합니다.
• 캐시 문제와 코드 문제를 구분해야 합니다.
• 팀 문서에 Metro 캐시 초기화 절차를 남겨두면 좋습니다.
• monorepo나 외부 디렉터리 symlink 구조에서는 감시 범위를 특히 주의해야 합니다.

듀오랩스가 보는 관점

개발 환경 문제는 기능 버그처럼 보일 때가 많습니다. Watchman과 Metro의 역할을 이해하면 “코드가 안 먹는다”는 막연한 문제를 더 빠르게 진단할 수 있습니다.