📋 package.json 완전 해부 — 모든 필드의 목적과 실전 패턴

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏷️ 정체성 필드
• 🔒 private & repository
• ⚙️ engines & browserslist
• 🚪 진입점 필드
• 📁 type
• 🌲 sideEffects
• 📤 files
• 🔧 config & workspaces
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🐣 영철이의 퇴근 일기
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 20분(전체) / 핵심 파트만: 10분 (private, engines, exports)

🗺️ 이 문서의 흐름
정체성 필드 → 실수 방지 필드 → 실행 환경 선언 → 진입점 설계 → Tree Shaking 힌트 → 배포 파일 제어

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

• "private": true 가 왜 Next.js 앱에 필수인지 설명할 수 있다
• engines 필드로 팀 전체의 Node.js 버전을 강제할 수 있다
• main, module, exports 의 차이를 정확히 구분할 수 있다
• "type": "module" 이 무엇을 바꾸는지 알고 Next.js 에서 어떻게 적용되는지 이해한다
• sideEffects 로 Tree Shaking 을 최적화할 수 있다

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

• 🐣 영철 ( 신입 ): "영호 리드 님, package.json 에 있는 필드 중에 name, version, dependencies 빼고는 왜 있는지 모르겠어요. private, engines, sideEffects, exports 같은 건 진짜 필요한 건가요? 그냥 없어도 되는 거 아닌가요? 특히 내부 UI 라이브러리(@youngsoo/ui) 만들 때 exports 를 어떻게 설정해야 하는지 모르겠어서 그냥 main 하나만 넣었는데 번들 사이즈가 너무 크게 나왔어요."
• 🦁 영호 ( 리드 ): "영철 님, exports 를 설정 안 하면 라이브러리 전체가 번들에 들어가요. 예를 들어 @youngsoo/ui 에서 버튼 컴포넌트 하나만 쓰는데 라이브러리 코드 전부가 들어오는 거예요. sideEffects: false 와 exports 를 제대로 세팅하면 Tree Shaking 이 작동해서 쓰는 것만 번들에 들어가요. 그리고 private: true 없으면 실수로 npm 에 올릴 수도 있어요."

🤔 왜 알아야 하는가

영철이가 영수네 커뮤니티 팀의 공유 UI 라이브러리 @youngsoo/ui 를 만들었다. 버튼, 모달, 인풋 등 20개 컴포넌트가 들어있다. 메인 앱에서 버튼 하나를 가져와 쓰는데, 번들 분석기를 돌려보니 @youngsoo/ui 의 모든 컴포넌트 코드가 번들에 들어있었다.

원인은 package.json 의 exports 와 sideEffects 설정이 없었기 때문이었다. 번들러가 "이 라이브러리의 어느 파일을 쓰지 않아도 되는지" 판단할 수 없어서 전부 포함시켜버린 것이다.

package.json 의 각 필드는 단순한 메타데이터가 아니다. 번들 최적화, 실수 방지, 팀 협업, 런타임 환경 강제에 직접 영향을 미치는 설정들이다.

🏷️ 정체성 필드 — name, version, description, keywords

{
  "name": "@youngsoo/ui",
  "version": "1.4.2",
  "description": "영수네 커뮤니티 공유 UI 컴포넌트 라이브러리",
  "keywords": ["react", "ui", "components", "youngsoo"],
  "homepage": "https://ui.youngsoo.dev",
  "bugs": {
    "url": "https://github.com/youngsoo-team/ui/issues"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/youngsoo-team/ui.git"
  },
  "license": "MIT"
}

name 규칙

✅ 올바른 이름:
  youngsoo-community     (소문자, 하이픈)
  @youngsoo/ui           (스코프 패키지)
  my-next-app            (소문자, 하이픈)

❌ 잘못된 이름:
  YoungsooCommunity      (대문자 금지)
  youngsoo community     (공백 금지)
  my_app                 (언더스코어는 지양)

• 214자 이하
• URL-safe 문자만 사용
• 대문자 사용 불가 (스코프 패키지도 동일)

version — SemVer 필수

"version": "1.4.2"
//          ^ ^ ^
//          | | └─ PATCH: 버그 수정
//          | └─── MINOR: 기능 추가 (하위 호환)
//          └───── MAJOR: 파괴적 변경 (Breaking Change)

💡 버전 올리는 명령어:

npm version patch    # 1.4.2 → 1.4.3
npm version minor    # 1.4.2 → 1.5.0
npm version major    # 1.4.2 → 2.0.0

이 명령어는 package.json 의 버전을 수정하고 git 태그도 자동으로 생성한다.

🔒 private & repository — 실수 방지와 팀 협업

private — 공개 배포 사고 방지

{
  // 🦁 [초핵심] 이 레포지토리는 "최종 앱(서비스)" 이고 라이브러리가 아니므로
  // 절대로 npm 퍼블릭 저장소에 배포(publish)되면 안 된다는 강한 선언입니다!
  // 이거 한 줄 없으면 소스 코드가 외부에 유출될 수 있습니다.
  "private": true
}

이 한 줄이 막아주는 재앙:

# "private": true 가 없는 상태에서
npm publish
# → 회사 내부 Next.js 앱 전체가 공개 npm 레지스트리에 올라감
# → 소스코드, 환경변수 힌트, 비즈니스 로직 전부 공개

🔥 황금 규칙: Next.js 앱(최종 결과물)에는 항상 "private": true 를 넣어라. npm 에 배포할 라이브러리에만 private 를 빼면 된다.

repository — 팀 도구와 연동

{
  "repository": {
    "type": "git",
    "url": "https://github.com/youngsoo-team/community.git",
    "directory": "packages/ui"
  }
}

이 필드가 채워지면 다음이 가능해진다:

npm docs           # repository 의 docs 링크 자동 열기
npm bugs           # bugs.url 자동 열기
npm repo           # repository URL 자동 열기

모노레포 구조에서는 "directory" 로 서브 패키지 경로를 명시한다.

⚙️ engines & browserslist — 실행 환경 선언

engines — Node.js / npm 버전 강제

{
  "engines": {
    "node": ">=18.17.0",
    "npm": ">=9.0.0"
  }
}

이 필드만으로는 경고만 출력된다. 실제로 버전을 강제하려면 .npmrc 설정이 필요하다:

# .npmrc
engine-strict=true

이제 Node 버전이 맞지 않으면 npm install 자체가 실패한다:

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: 'youngsoo-community@1.0.0',
npm warn EBADENGINE   required: { node: '>=18.17.0' },
npm warn EBADENGINE   current: { node: 'v16.20.0', npm: '8.19.4' }
npm warn EBADENGINE }
npm error code EBADENGINE

.nvmrc 와 함께 완벽한 팀 환경 통일:

# .nvmrc (프로젝트 루트)
18.17.0

# 팀원이 프로젝트 클론 후 실행하는 순서
nvm use          # .nvmrc 에 맞는 Node 자동 사용
npm install      # engines 체크 통과

browserslist — 지원 브라우저 선언

{
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

이 설정은 Babel, PostCSS(Autoprefixer), SWC 등이 참조하여 어느 브라우저까지 지원할 폴리필을 넣을지 결정한다. Next.js 도 내부적으로 이 설정을 참조한다.

🚪 진입점 필드 — main, module, exports

이 세 필드는 주로 라이브러리 패키지를 만들 때 중요하다. @youngsoo/ui 같은 내부 패키지를 만들 때 반드시 알아야 한다.

main — CommonJS 진입점 (레거시)

{
  "main": "./dist/index.js"
}

require('@youngsoo/ui') 를 실행하면 여기서 지정한 파일을 읽는다. 단, 이것만 있으면 Tree Shaking 이 불가능하다. 진입점 하나에서 모든 것을 export 하기 때문이다.

module — ESM 진입점 (번들러용)

{
  "main": "./dist/index.cjs.js",
  "module": "./dist/index.esm.js"
}

module 필드는 Node.js 표준은 아니지만 Webpack, Rollup, Vite 같은 번들러가 참조한다. ESM 형식의 파일을 지정하면 Tree Shaking 가능성이 열린다.

exports — 현대적 진입점 (권장)

{
  // 💡 패키지 내부의 길을 터주는 네비게이션입니다. (진입점 통제 + 최적화)
  "exports": {
    // 1️⃣ import { Button } from '@youngsoo/ui' 할 때 어디로 갈지
    ".": {
      "import":  "./dist/index.esm.js", // 최신 브라우저/번들러용 (Tree Shaking 친화적)
      "require": "./dist/index.cjs.js", // 구형 환경이나 require() 로 부를 때
      "types":   "./dist/index.d.ts"    // TypeScript 자동완성을 위해 읽을 파일
    },
    // 2️⃣ import { Button } from '@youngsoo/ui/button' 할 때 어디로 갈지
    // 🦁 갓벽한 최적화를 위해 경로별로 정확하게 목적지 파일을 각각 안내해줍니다!
    "./button": {
      "import":  "./dist/button.esm.js",
      "require": "./dist/button.cjs.js",
      "types":   "./dist/button.d.ts"
    },
    // 3️⃣ 모달 컴포넌트를 찾을 때의 경로
    "./modal": {
      "import":  "./dist/modal.esm.js",
      "require": "./dist/modal.cjs.js",
      "types":   "./dist/modal.d.ts"
    }
  }
}

exports 의 강력한 점:

// 🐣 영철 (이전) — 전체 라이브러리를 가져옴
import { Button } from '@youngsoo/ui'
// → exports 없으면 dist/index.js 전체 번들에 포함
 
// 🦁 영호 (이후) — 버튼만 가져옴
import { Button } from '@youngsoo/ui/button'
// → exports 있으면 dist/button.esm.js 만 번들에 포함

서브 경로 접근 제어:

{
  "exports": {
    "./internal/*": null
  }
}

exports 에 명시되지 않은 경로는 외부에서 접근 불가. @youngsoo/ui/internal/secret 접근 시도 시 에러.

📁 type — CommonJS vs ESM 선택

{
  "type": "module"
}

주의: Next.js 앱에서의 함정

// ❌ Next.js 앱의 package.json 에 이걸 추가하면 문제 발생
{
  "type": "module"
}

Next.js 는 내부적으로 CommonJS 와 ESM 을 모두 처리하는 복잡한 설정을 갖추고 있다. "type": "module" 을 앱 루트에 추가하면 Next.js 설정 파일(next.config.js 등)의 동작에 영향을 줄 수 있다. Next.js 앱에서는 이 필드를 건드리지 않는 것이 안전하다.

라이브러리에서는 적극 활용:

// @youngsoo/ui/package.json
{
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.js",    // type: module 이므로 .js 가 ESM
      "require": "./dist/index.cjs"   // .cjs 는 항상 CommonJS
    }
  }
}

🌲 sideEffects — Tree Shaking 을 위한 힌트

{
  "sideEffects": false
}

Tree Shaking 이란: 사용하지 않는 코드를 번들에서 제거하는 최적화.

// @youngsoo/ui/src/index.ts
export { Button } from './button'
export { Modal } from './modal'
export { Input } from './input'
// ... 20개 컴포넌트
 
// 앱에서 버튼만 사용
import { Button } from '@youngsoo/ui'

sideEffects: false 가 없으면 번들러는 "이 라이브러리의 다른 파일들을 import 해도 부작용(전역 변수 변경 등)이 생길 수 있으니 전부 포함하자" 고 판단한다.

sideEffects: false 를 선언하면 번들러가 "이 라이브러리는 import 해도 부작용이 없다, Tree Shaking 해도 안전하다" 고 판단한다.

CSS 파일은 예외 처리:

{
  "sideEffects": [
    "*.css",
    "*.scss",
    "./src/polyfills.js"
  ]
}

CSS 파일은 import 자체가 부작용(스타일 주입)이므로 예외로 선언한다.

🔥 Before / After:

❌ sideEffects 없음 (영철의 초기 설정)

{ "name": "@youngsoo/ui", "main": "./dist/index.js" }

결과: Button 하나 import 해도 20개 컴포넌트 전체 번들 포함 → 불필요한 +200kb

✅ sideEffects + exports 설정 (영호의 리뷰 후)

{
  "sideEffects": ["*.css"],
  "exports": {
    "./button": { "import": "./dist/button.esm.js" }
  }
}

결과: Button 만 번들에 포함 → 최소 크기

📤 files — 배포할 파일 선택

{
  "files": [
    "dist/",
    "src/",
    "README.md"
  ]
}

npm publish 시 files 에 명시된 것만 패키지에 포함된다. 지정하지 않으면 .gitignore 에 없는 모든 파일이 포함된다.

항상 제외되는 파일 (명시 불필요):

• .git/
• node_modules/
• .npmrc

항상 포함되는 파일 (명시 불필요):

• package.json
• README.md
• LICENSE

💡 확인 방법:

npm pack --dry-run    # 실제 배포 없이 포함될 파일 목록 확인

🔧 config & workspaces

config — 스크립트에서 사용할 변수

{
  "config": {
    "port": "3000"
  },
  "scripts": {
    "dev": "next dev -p $npm_package_config_port"
  }
}

npm run dev    # next dev -p 3000 으로 실행
npm config set youngsoo-community:port 4000   # 개인 설정으로 덮어쓰기 가능

workspaces — 모노레포 기초

{
  "name": "youngsoo-monorepo",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

youngsoo-monorepo/
  package.json          ← 루트 (위 설정)
  apps/
    community/          ← Next.js 앱
    admin/              ← 관리자 앱
  packages/
    ui/                 ← @youngsoo/ui 라이브러리
    utils/              ← @youngsoo/utils 공유 유틸

workspaces 에 대한 상세 내용은 별도 가이드에서 다룬다.

🏁 이번에 배운 내용 총정리

📝 마무리 퀴즈

Q1. "private": true 필드의 역할은?

a) 패키지를 비밀번호로 보호한다
b) npm publish 명령 실행 시 레지스트리에 업로드되는 것을 막는다
c) node_modules 폴더를 숨긴다
d) 팀원이 패키지를 설치하지 못하게 막는다

✅ 정답: b — npm publish 실행을 막는다

💡 상세 해설:

• 원리 설명: "private": true 가 있으면 npm publish 실행 시 npm ERR! This package has been marked as private 에러가 발생하며 중단된다. 회사 내부 Next.js 앱이 실수로 공개 레지스트리에 올라가는 것을 방지하는 안전장치다.
• 오답 피드백: a — 비밀번호와 무관하다. c — node_modules 가시성과 무관하다. d — 설치 자체는 막지 않는다.
• 📌 핵심 기억법: "private: true = 공개 npm 에 올라가지 않는다."

Q2. 아래 상황에서 sideEffects: false 를 설정했을 때 올바른 동작은?

// @youngsoo/ui 라이브러리에서 Button 만 import
import { Button } from '@youngsoo/ui'

a) 라이브러리 전체가 번들에 포함된다
b) 번들러가 Button 관련 코드만 번들에 포함하고 나머지는 제외한다
c) import 가 실패하고 에러가 발생한다
d) 라이브러리를 아예 번들에서 제외한다

✅ 정답: b — 번들러가 Button 관련 코드만 포함한다

💡 상세 해설:

• 원리 설명: sideEffects: false 는 번들러에게 "이 패키지의 파일들은 import 해도 전역 상태를 변경하는 부작용이 없다"고 알려준다. 번들러는 이 힌트를 받아 실제로 사용되는 Button 코드만 번들에 포함하고, 사용하지 않는 Modal, Input 등은 제외(Tree Shake)한다.
• 오답 피드백: a — sideEffects: false 없이 main 만 설정했을 때의 동작이다. c — 설정이 있어도 import 는 정상 작동한다. d — 라이브러리를 완전히 제외하는 것이 아니라 사용한 부분만 선택적으로 포함한다.
• 📌 핵심 기억법: "sideEffects: false = 번들러에게 'Tree Shake 해도 안전해' 라는 신호."

Q3. 🐣 영철이의 테스트 타임 — 긴급 디버깅

영수 PM 이 슬랙을 보냈다. "영철 님, @youngsoo/ui 에서 버튼 하나만 쓰는데 Lighthouse 에서 번들 사이즈 경고가 계속 나와요. 분석해보니 UI 라이브러리 전체가 번들에 들어있어요. 어떻게 된 건가요?"

영철이가 @youngsoo/ui/package.json 을 보니 이렇게 되어있었다:

{
  "name": "@youngsoo/ui",
  "main": "./dist/index.js",
  "version": "1.0.0"
}

문제의 원인과 올바른 수정 방법을 설명하라.

✅ 정답: sideEffects 와 exports 가 없어서 Tree Shaking 이 불가능했다

{
  "name": "@youngsoo/ui",
  "version": "1.0.0",
  "main": "./dist/index.cjs.js",
  "module": "./dist/index.esm.js",
  "sideEffects": ["*.css"],
  "exports": {
    ".": {
      "import":  "./dist/index.esm.js",
      "require": "./dist/index.cjs.js",
      "types":   "./dist/index.d.ts"
    },
    "./button": {
      "import":  "./dist/button.esm.js",
      "require": "./dist/button.cjs.js",
      "types":   "./dist/button.d.ts"
    }
  }
}

💡 상세 해설:

• 원인: main 만 있으면 번들러는 ./dist/index.js 라는 진입점 하나에서 모든 것을 export 하는 구조로 인식한다. 사용하지 않는 코드가 있어도 "부작용이 있을 수 있으니" 전부 포함시킨다.
• sideEffects 효과: 번들러에게 "CSS 를 제외한 코드에는 부작용이 없다"고 알려줘 Tree Shaking 을 활성화한다.
• exports 효과: 서브 경로(./button)를 명시해주면 import { Button } from '@youngsoo/ui/button' 으로 버튼 번들만 명시적으로 가져올 수 있어, 번들러가 더 정밀하게 최적화할 수 있다.
• 📌 핵심 기억법: "라이브러리를 만든다면: exports 로 진입점 설계 + sideEffects: false 로 Tree Shaking 허용 = 최적화 완성."

🐣 영철이의 퇴근 일기

오늘은 지하철 타기 전에 회사 근처 카페에 잠깐 앉았다. 커피 한 잔 시키고 오늘 배운 것 머릿속에서 정리하는 중.

package.json 을 그냥 "이름이랑 버전 쓰는 파일" 로만 알았는데, 오늘 보니까 배포 실수 방지, 번들 최적화, 팀 환경 통일까지 다 여기서 출발하는 거였다. 특히 sideEffects: false 는 진짜 몰랐다. 내가 만든 @youngsoo/ui 에서 버튼 하나만 쓰는데 20개 컴포넌트가 다 번들에 들어간 게 그것 때문이었구나. 영수 님이 번들 사이즈 얘기할 때 살짝 식은땀 났다.

💡 오늘의 교훈: "package.json 은 프로젝트의 계약서다. private, engines, exports, sideEffects — 이 네 개를 챙기는 것이 라이브러리를 제대로 만드는 시작이다."

그나저나 exports 필드 설정하고 나서 번들 사이즈가 확 줄었다. 괜히 뿌듯하다. 영숙 님이 다음엔 좀 빠르다고 할 것 같은데... 헬스장 가야지, 빡세게 하루 보냈으니까.

🔗 더 알아보기

• npm 공식 문서 — package.json 전체 필드
• Node.js 공식 문서 — Package exports
• Webpack — Tree Shaking 가이드
• npm 공식 문서 — npmrc