devDependencies인데 왜 설치가 안 되지? 배포 환경에서 겪은 삽질 공유

🙋‍♀️ 시작은 사소한 devtools 에러였다

React Query를 잘 쓰고 있었고,
개발 중엔 @tanstack/react-query-devtools도 함께 쓰고 있었다.
쿼리 상태를 실시간으로 볼 수 있고, 캐시도 초기화할 수 있어서 아주 유용했다.

 

그런데…
배포 후 콘솔에 이런 에러가 떴다.

Module not found: Error: Can't resolve '@tanstack/react-query-devtools'

로컬에선 문제 없었는데 배포 환경에선 왜 안 되는 걸까?

 

---

 

🔍 문제 요약

 

1. 나는 @tanstack/react-query-devtools를 devDependencies에 넣었음

2. 로컬 개발환경에서는 문제없이 잘 동작

3. 그런데 배포 서버에서는 모듈을 못 찾는 에러 발생

 

---

 

🤯 원인은 NODE_ENV=production

 

npm은 기본적으로 NODE_ENV=production이면
devDependencies에 있는 패키지들을 아예 설치하지 않음

npm install --production

즉, 배포 환경에서는 devDependencies가 날아가고,
필요한 devtools도 없으니 에러가 나는 것.

 

---

 

⚠️ 문제를 더 꼬이게 한 것: 커스텀 환경변수

 

내 프로젝트는 개발/운영을 나눌 때
NODE_ENV 외에 별도의 환경변수를 사용하고 있었다. 예를 들면:

NODE_ENV=development

 

실제로 배포 서버에서는:

• NODE_ENV=production → npm은 devDependencies 설치 ❌
• NODE_ENV=development → 서비스는 여전히 개발 모드처럼 동작
  → devtools를 불러오려고 함

설치는 안 됐는데, 불러오려고 하니 당연히 에러 발생.

 

---

 

✅ 해결 방법

devtools를 dependencies로 옮김

npm install @tanstack/react-query-devtools

이제 어떤 환경에서도 설치는 됨.

 

2. 코드에서 조건부 로딩 처리

import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

const isDev = import.meta.env.NODE_ENV === 'development'

function App() {
  return (
    <>
      {/* 앱 내용 */}
      {isDev && <ReactQueryDevtools initialIsOpen={false} />}
    </>
  )
}

이렇게 하면 실제 devtools는 개발 환경에서만 렌더링된다.

 

---

 

🧠 정리: 이럴 땐 dependencies로

 

상황처리	방식
로컬에서만 사용하는 도구	devDependencies (기본)
배포 환경에서도 필요한 도구인데, 커스텀 ENV로 개발모드처럼 동작	✅ dependencies에 넣어야 함
실행은 개발처럼 하되, 빌드는 운영처럼 하는 복합 환경	✅ devtools도 함께 배포되게 해야 함

 

devtools 같은 개발 전용 도구들은
보통 당연히 devDependencies에 넣는다고 생각하지만,
커스텀 환경변수를 써서 개발/운영 구분하는 프로젝트에선 예외가 생긴다.

 

이번 삽질을 통해 확실히 배운 점은:

"npm은 NODE_ENV=production만 본다. 나머지 ENV는 네 코드가 알아서 처리해라."