🌿 의존성 4종 세트 — dependencies, devDependencies, peerDependencies, overrides

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 📦 dependencies
• 🔧 devDependencies
• 🤝 peerDependencies
• 🎲 optionalDependencies
• 🔧 overrides
• 🚀 Next.js 프로젝트 의존성 분류 실전
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🐣 영철이의 퇴근 일기
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 20분(전체) / 핵심 파트만: 10분 (peerDependencies + Next.js 분류)

🗺️ 이 문서의 흐름
런타임 필수(dependencies) → 개발 도구(devDependencies) → peerDependencies 원리 → overrides 충돌 해결 → Next.js 실전 분류

🎯 이 문서를 다 읽으면 할 수 있는 것

• dependencies 와 devDependencies 를 항상 올바르게 구분할 수 있다
• peerDependencies 가 왜 존재하는지, React 인스턴스 중복 문제를 예방하는 원리를 설명할 수 있다
• overrides 로 간접 의존성의 버전을 강제 지정할 수 있다
• Next.js 프로젝트에서 tailwindcss, prisma, @prisma/client 의 위치를 즉시 판단할 수 있다

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 🐣 영철 ( 신입 ): "리드 님, 제가 @youngsoo/ui 라이브러리 만들면서 react 를 dependencies 에 넣었는데, 메인 앱에서 훅 오류가 났어요. Invalid hook call 이요. 그리고 prisma 랑 @prisma/client 중에 뭐가 devDependencies 인지도 헷갈려요. 빌드할 때 쓰이는 건 전부 devDependencies 아닌가요?"
• 🦁 영호 ( 리드 ): "영철 님, Invalid hook call 은 React 인스턴스가 두 개 생겼을 때 나는 에러예요. @youngsoo/ui 가 자기 node_modules 에 React 를 따로 들고왔거든요. peerDependencies 를 이해하면 왜 그게 문제인지 바로 알 수 있어요. 그리고 devDependencies 판단 기준은 '빌드할 때 쓰이느냐' 가 아니라 '프로덕션 서버가 실행 중에 이 패키지가 필요하냐' 예요."

🤔 왜 알아야 하는가

영수네 커뮤니티 팀은 Next.js 앱과 내부 UI 라이브러리 @youngsoo/ui 를 함께 개발하고 있다. 어느 날 영철이가 UI 라이브러리에서 useState 를 쓰는 컴포넌트를 만들었는데, 메인 앱에서 가져다 쓰자마자 이런 에러가 났다:

Uncaught Error: Invalid hook call.
Hooks can only be called inside of the body of a function component.

진단해보니 @youngsoo/ui/node_modules/react 와 메인 앱의 node_modules/react 가 별도로 존재하고 있었다. 두 개의 React 인스턴스 가 생긴 것이다.

원인은 영철이가 @youngsoo/ui/package.json 에 react 를 dependencies 에 넣었기 때문이다. 이 문제를 이해하는 것이 peerDependencies 의 핵심이다.

📦 dependencies — 런타임 필수 코드

{
  "dependencies": {
    // 💡 질문 1개만 던져보세요: "내 서비스가 돌아가는 동안 이 코드가 필요한가?"
    // 서버가 돌 때 렌더링하려면 next, react 가 꼭 필요하죠!
    "next": "^14.1.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "jotai": "^2.6.4",
    // DB를 찌르려면 @prisma/client 도 런타임에 호출되어야 합니다.
    "@prisma/client": "^5.9.1"
  }
}

판단 기준 — 딱 하나만 기억해라:

"프로덕션 서버가 실행 중에 이 패키지의 코드가 실행되는가?"

YES → dependencies / NO → devDependencies

설치 동작:

npm install                     # dependencies + devDependencies 모두 설치
npm install --production        # dependencies 만 설치
NODE_ENV=production npm install # dependencies 만 설치

🔧 devDependencies — 개발 도구, 빌드 타임에만 필요한 것

{
  "devDependencies": {
    // 🦁 "사용자에게 배포될 때는 안 볼 녀석들" 입니다.
    // 타입스크립트처럼 코드 짤 때만 쓰는 도구 (나중에 자바스크립트로 변신하니까요!)
    "typescript": "^5.3.3",
    "@types/react": "^18.2.48",
    // 린트, 포매터도 배포서버에는 올라갈 이유가 없죠.
    "eslint": "^8.56.0",
    "prettier": "^3.2.4",
    // tailwind 도 빌드할 때 CSS 파일을 쫙 뽑아내고 나면 역할 끝!
    "tailwindcss": "^3.4.1",
    "prisma": "^5.9.1"
  }
}

헷갈리기 쉬운 케이스 — 왜 이것들이 devDependencies 인가?

🐣 영철: "tailwindcss 가 devDependencies 인 게 아직도 좀 이상한데요?"

🦁 영호: "Next.js 빌드 과정을 그림으로 그려볼게요:

개발 시
 소스 코드 (.tsx)
   + Tailwind 클래스 스캔 (tailwindcss 사용)
   + PostCSS 처리 (postcss, autoprefixer 사용)
   ↓ 빌드
.next/static/css/xxx.css (완성된 CSS 파일)

프로덕션 서버
 .next/ 폴더만 실행
   → tailwindcss? 필요 없음. CSS 이미 만들어짐.

빌드 도구는 빌드할 때만 필요해요. 완성된 건물 짓고 나면 공사 도구 치워도 돼요."

🤝 peerDependencies — "나는 네 것을 공유할게"

peerDependencies 가 없었다면 생기는 문제

node_modules/
  react/                          ← 내 앱의 React 18.2.0
  @youngsoo/ui/
    node_modules/
      react/                      ← 라이브러리가 들고온 또 다른 React 18.2.0

버전이 같아도 문제다. node_modules 내 다른 경로에 있으면 Node.js 는 다른 모듈로 취급한다. React 는 내부적으로 단일 전역 인스턴스를 가정하고 동작하기 때문에, 두 개의 인스턴스가 공존하면:

• useState, useEffect 등 훅이 "어떤 React 에 등록해야 하지?" 혼동 → Invalid hook call
• Context.Provider 의 값이 다른 React 인스턴스의 useContext 로 읽히지 않음 → undefined

peerDependencies 의 해결책

// @youngsoo/ui/package.json
{
  // 💡 "내가 직접 설치 안 할테니, 날 쓰는 앱아! 네가 설치한 리액트 좀 빌려줘!"
  // 이렇게 해야 쌍둥이 리액트가 생겨서 훅 에러가 나는 걸 막을 수 있어요.
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  // 🦁 "하지만 내가 이 라이브러리를 지금 개발하고 테스트하려면 리액트가 필요하니까..."
  // 개발용으로만 임시로 설치해둡니다.
  "devDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

의미: "나(@youngsoo/ui)는 React 가 필요하지만, 직접 설치하지 않을게. 나를 사용하는 앱이 React 를 제공해줘. 나는 그것을 공유해서 쓸게."

결과:

node_modules/
  react/                    ← 앱과 라이브러리가 공유하는 단 하나의 React 18.2.0
  @youngsoo/ui/             ← 자체 node_modules/react 없음

devDependencies 에도 넣는 이유: 라이브러리 자체를 개발하고 테스트할 때는 React 가 실제로 설치되어 있어야 하기 때문이다.

npm v7+ 에서 peerDependencies 자동 설치

# npm v7+ 는 peerDependencies 를 자동으로 설치함
# (npm v6 이하에서는 경고만 표시하고 자동 설치 안 함)
 
npm install @youngsoo/ui
# → @youngsoo/ui 설치 + peerDependencies 인 react, react-dom 도 함께 설치

peerDependenciesMeta — 선택적 peer

{
  "peerDependencies": {
    "react": "^18.0.0",
    "next": ">=13.0.0"
  },
  "peerDependenciesMeta": {
    "next": {
      "optional": true
    }
  }
}

next 는 있으면 Next.js 전용 기능을 활성화하지만, 없어도 기본 기능은 동작함을 의미한다.

🎲 optionalDependencies — 있으면 좋고, 없어도 괜찮아

{
  "optionalDependencies": {
    "fsevents": "^2.3.3"
  }
}

설치에 실패해도 전체 npm install 이 중단되지 않는다.

주요 사용 케이스:

• fsevents — macOS 전용 파일 감시 모듈 (Linux/Windows 에서는 설치 실패해도 무방)
• 특정 OS 전용 네이티브 모듈
• 있으면 성능이 향상되지만 없어도 기본 기능은 동작하는 패키지

코드에서는 존재 여부를 확인해야 한다:

let fsevents
try {
  fsevents = require('fsevents')
} catch (e) {
  // fsevents 가 없을 때 fallback
  fsevents = null
}

🔧 overrides — 버전 충돌의 외과적 해결

overrides 는 npm 8.3+ 에서 지원하는 기능으로, 직접 의존성뿐 아니라 간접 의존성의 버전까지 강제 지정할 수 있다.

사용 케이스 1 — 간접 의존성의 보안 취약점 수정

내 앱
  └─ some-library@2.0.0
       └─ vulnerable-pkg@1.0.0  ← 취약점 발견! 1.2.0 에서 패치됨

some-library 가 아직 업데이트를 안 했을 때:

{
  "overrides": {
    "vulnerable-pkg": "^1.2.0"
  }
}

사용 케이스 2 — 특정 패키지 안의 의존성만 수정

{
  "overrides": {
    "some-library": {
      "vulnerable-pkg": "^1.2.0"
    }
  }
}

some-library 가 사용하는 vulnerable-pkg 만 버전을 올리고, 다른 곳에서 쓰는 건 건드리지 않는다.

사용 케이스 3 — 버전 통일 (중복 패키지 제거)

{
  "dependencies": {
    "next": "^14.1.0",
    "some-old-lib": "^3.0.0"
  },
  "overrides": {
    "some-old-lib": {
      "react": "$react"
    }
  }
}

$react 는 dependencies.react 의 버전을 참조하는 표현식. some-old-lib 가 들고오는 React 를 메인 앱의 React 와 동일하게 강제한다.

🦁 영호의 조언: "overrides 는 '외과적 수술' 이에요. 항상 가장 좁은 범위로 적용하고, 왜 이 override 가 필요한지 주석으로 남겨야 해요."

{
  "overrides": {
    // react-beautiful-dnd 가 14.3.0 에서 Breaking Change 넣음 (SemVer 위반)
    // 14.2.0 이 마지막 안정 버전
    "react-beautiful-dnd": "14.2.0"
  }
}

🚀 Next.js 프로젝트 의존성 분류 실전

영수네 커뮤니티의 완성형 의존성 분류:

{
  "dependencies": {
    "next": "^14.1.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
 
    "@prisma/client": "^5.9.1",
    "next-auth": "^4.24.5",
 
    "jotai": "^2.6.4",
    "@tanstack/react-query": "^5.18.0",
    "@tanstack/react-query-devtools": "^5.18.0",
 
    "zod": "^3.22.4",
    "socket.io-client": "^4.7.2",
 
    "@youngsoo/ui": "workspace:*"
  },
 
  "devDependencies": {
    "typescript": "^5.3.3",
    "@types/react": "^18.2.48",
    "@types/react-dom": "^18.2.18",
    "@types/node": "^20.11.5",
 
    "eslint": "^8.56.0",
    "eslint-config-next": "^14.1.0",
    "prettier": "^3.2.4",
 
    "tailwindcss": "^3.4.1",
    "autoprefixer": "^10.4.17",
    "postcss": "^8.4.33",
 
    "prisma": "^5.9.1",
 
    "jest": "^29.7.0",
    "@testing-library/react": "^14.1.2",
    "@testing-library/jest-dom": "^6.4.1",
    "jest-environment-jsdom": "^29.7.0",
 
    "husky": "^9.0.10",
    "lint-staged": "^15.2.2",
    "@next/bundle-analyzer": "^14.1.0",
    "cross-env": "^7.0.3"
  }
}

분류 근거 상세 해설

💡 @tanstack/react-query-devtools 주의: 이 패키지는 내부적으로 process.env.NODE_ENV !== 'production' 일 때만 실제 devtools UI 를 렌더링한다. 따라서 devDependencies 에 넣어도 되지만, 일부 번들러 설정에 따라 조건부 import 가 안 되는 경우가 있어 dependencies 에 넣는 것이 안전하다.

🏁 이번에 배운 내용 총정리

📝 마무리 퀴즈

Q1. prisma 와 @prisma/client 의 올바른 의존성 위치는?

a) 둘 다 dependencies
b) 둘 다 devDependencies
c) prisma 는 devDependencies, @prisma/client 는 dependencies
d) prisma 는 dependencies, @prisma/client 는 devDependencies

✅ 정답: c

💡 상세 해설:

• @prisma/client → dependencies: Next.js 서버 컴포넌트나 Route Handler 에서 실행 중에 DB 쿼리를 날린다. prisma.$connect(), prisma.user.findMany() 같은 코드가 프로덕션 서버에서 실행된다. 런타임 필수.
• prisma (CLI) → devDependencies: npx prisma migrate dev, npx prisma generate 같은 명령어는 개발 중에만 실행된다. 프로덕션 서버에서 prisma CLI 를 직접 호출하는 일은 없다.
• 📌 핵심 기억법: "@prisma/client = 서버가 DB 에 접속할 때 쓰는 런타임 코드. prisma = 스키마 관리 CLI 도구."

Q2. 아래 에러가 발생하는 가장 직접적인 원인은?

Uncaught Error: Invalid hook call.
Hooks can only be called inside of the body of a function component.

a) React 버전이 너무 낮아서 훅을 지원하지 않는다
b) 서버 컴포넌트에서 useState 를 사용했다
c) 두 개의 React 인스턴스가 공존해서, 훅이 어느 인스턴스에 등록해야 할지 혼란이 생겼다
d) useEffect 를 잘못된 위치에서 호출했다

✅ 정답: c — 두 개의 React 인스턴스 문제

💡 상세 해설:

• 원리 설명: React 훅은 내부적으로 단일 전역 React 인스턴스의 상태 저장소에 데이터를 읽고 쓴다. 라이브러리가 dependencies 에 react 를 넣으면 node_modules/library/node_modules/react 라는 별도 인스턴스가 생긴다. 이 인스턴스는 앱의 node_modules/react 와 다른 객체이므로, 훅이 "어디에 등록해야 하지?" 혼란을 겪는다.
• 해결: 라이브러리의 react 를 peerDependencies 로 이동하면 호스트 앱의 React 인스턴스를 공유해 이 문제가 사라진다.
• 📌 핵심 기억법: "Invalid hook call = React 인스턴스 두 개. 라이브러리는 peerDependencies 로 해결."

Q3. 🐣 영철이의 테스트 타임 — 라이브러리 트레이드오프

영수네 팀이 @youngsoo/ui 라이브러리의 package.json 을 설계하는 회의가 열렸다. 각 팀원이 의견을 냈다.

• 🐣 영철: "react 를 dependencies 에 넣을게요. 라이브러리에서도 React 가 필요하잖아요."
• 👔 영수 (PM): "저는 잘 모르겠는데, 두 방식의 장단점이 뭔지 설명해줘요."
• 🦁 영호: "?"

영호 리드의 입장에서 올바른 결론과 근거를 설명하라.

✅ 정답: react 는 peerDependencies 와 devDependencies 에 동시에 넣어야 한다

{
  "name": "@youngsoo/ui",
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

💡 상세 해설:

• dependencies 에 넣으면: 호스트 앱(youngsoo-community)에 이미 react@18 이 설치되어 있어도, @youngsoo/ui 가 자신의 node_modules 에 또 다른 React 를 설치한다. → 두 인스턴스 → Invalid hook call + Context 단절.
• peerDependencies 에 넣으면: "나는 React 가 필요하지만 호스트 앱의 것을 쓸게" 라는 선언. npm 이 단일 node_modules/react 를 공유하도록 설계한다.
• devDependencies 에도 넣는 이유: 라이브러리 자체를 개발하거나 테스트할 때(jest, storybook 등) 실제로 React 가 설치되어 있어야 한다. peerDependencies 만 있으면 개발 환경에서 React 가 없어서 테스트가 안 돌아간다.
• 영수(PM) 에게 한 마디: "같은 React 를 공유해야 Context 와 훅이 정상 작동해요. 비용은 거의 없고 안정성은 크게 올라가요."
• 📌 핵심 기억법: "내가 만드는 것이 라이브러리라면 — 호스트 앱과 공유해야 할 것은 peerDependencies, 개발할 때 직접 쓸 것은 devDependencies 에도 함께."

🐣 영철이의 퇴근 일기

오늘 오후 내내 Invalid hook call 에러와 씨름했다. 처음엔 단순히 훅을 잘못 쓴 건 줄 알고 스택오버플로우를 뒤졌는데, 영호 리드 님이 "두 React 인스턴스 문제" 라고 딱 집어주셔서 원인을 찾았다.

@youngsoo/ui 에 react 를 peerDependencies 로 옮겼더니 에러가 바로 사라졌다. 왜 그게 해결되는지는 이제 완전히 이해한다. node_modules 경로가 하나로 통일되면서 React 인스턴스가 하나만 남는 거다.

💡 오늘의 교훈: "라이브러리를 만들 때 peerDependencies 를 빠뜨리면, 사용하는 앱에서 이유 모를 훅 오류가 터진다. 의존성의 공유 여부를 설계하는 것이 라이브러리 작성자의 책임이다."

퇴근하면서 걸어가다가 이것저것 머릿속에서 정리됐다. dependencies vs devDependencies 판단 기준 — "프로덕션 서버가 실행 중에 필요한가?" — 이거 하나만 기억해도 앞으론 헷갈리지 않을 것 같다.

내일은 npm install 이 내부에서 어떻게 lock 파일을 쓰는지 파봐야지. 오늘은 일찍 자야겠다. 좀 피곤하다.

🔗 더 알아보기

• npm 공식 문서 — dependencies 필드
• npm 공식 문서 — peerDependencies
• npm 공식 문서 — overrides
• React 공식 — Invalid hook call 에러 원인