📦 10. 모듈 시스템 — ESM과 CommonJS, 당신의 코드가 어느 세계에 살고 있는가

🎯 이 섹션을 읽고 나면:

• ESM(import/export)과 CommonJS(require/module.exports)의 근본 차이를 설명한다.
• Named export와 Default export를 언제 각각 사용해야 하는지 판단한다.
• 동적 import()로 코드 스플리팅을 구현하고, Tree Shaking 친화적 코드를 작성한다.

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 1. 왜 알아야 하는가?
• 📜 2. 모듈의 역사 — 왜 두 가지가 존재하는가?
• 🔀 3. ESM vs CJS 핵심 차이
• 📤 4. ESM Export 패턴
  • Named Export
  • Default Export
  • Named vs Default 언제 선택?
• ⚡ 5. 동적 import — 코드 스플리팅
• 🌳 6. Tree Shaking 친화적 코드 작성
• 📝 마무리 퀴즈
• 🐣 영철이의 퇴근 일기
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 18분(전체) / 핵심 파트만: 11분

🗺️ 이 문서의 흐름
[CJS vs ESM 역사] → [문법 차이] → [Export 패턴 선택] → [동적 import + Tree Shaking]

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

• Node.js에서 import를 쓰려면 왜 설정이 필요한지 설명한다.
• barrel export가 번들 크기에 어떤 영향을 주는지 안다.
• 무거운 라이브러리를 필요한 시점에만 로드하는 동적 import를 구현한다.

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

🐣 영철: "영호 님, Node.js 서버 코드에서는 require()를 쓰는데, 프론트 React 코드에서는 import를 써요. 그리고 Node.js에서도 .mjs 확장자를 쓰면 import가 된다는데... 이게 다 호환이 되나요? require랑 import가 뭐가 다른 건지 솔직히 잘 모르겠어요."

🦁 영호: "좋은 질문이야. require는 CJS(CommonJS)고, import는 ESM(ES Modules)이야. 이 둘은 단순히 문법 차이가 아니라 모듈을 읽는 시점과 방식 이 근본적으로 달라. 그리고 이 차이가 번들러의 Tree Shaking, 서버/클라이언트 환경 호환성에도 영향을 줘. 오늘 이거 한 번 제대로 이해해두면 esm이니 cjs니 하는 빌드 설정도 눈에 들어오게 될 거야."

🤔 1. 왜 알아야 하는가?

영수 님 백엔드는 require, 영철이 프론트는 import — 이 둘이 배포 직전에 처음 충돌한 날이 이 챕터 공부의 계기였다. 모듈 시스템을 이해하지 못하면 다음 상황에서 멘붕한다:

• "require is not defined in ES module scope" 에러
• Node.js에서 import 쓰려다 막히는 상황
• 번들 크기 최적화에서 "왜 안 쓰는 코드가 번들에 포함됐지?"
• TypeScript moduleResolution 설정에서 bundler, node16, NodeNext 선택 혼란

📜 2. 모듈의 역사 — 왜 두 가지가 존재하는가?

브라우저와 Node.js가 각자의 모듈 시스템을 발전시키다가 뒤늦게 합류하면서, 현재 두 시스템이 공존하는 과도기 상태다.

🔀 3. ESM vs CJS 핵심 차이

오프닝에서 영호 리드 님이 말한 "모듈을 읽는 시점과 방식이 근본적으로 달라"의 실체가 바로 이것입니다.

영수 님이 Node.js 서버에서 작성하던 방식과, 영철이가 브라우저 환경에서 작성하던 코드를 나란히 비교해 보겠습니다. 코드가 평가되는 시점의 차이를 상상하며 읽어보세요.

// CommonJS (CJS)
const fs = require("fs");                        // 동기 로드
const { readFile } = require("fs");              // 동적으로 꺼낼 수 있음
const moduleName = "fs";
const m = require(moduleName);                   // 변수로 require 가능!
 
module.exports = { myFunction };
module.exports.helper = helperFunction;
 
// ES Modules (ESM)
import fs from "fs";                             // 정적 로드 (파싱 시 결정)
import { readFile } from "fs";                   // Named import
// const m = import(moduleName);                 // 동적 import는 별도 문법
// import 경로에 변수 불가 — 정적으로 결정되어야 함
 
export const myFunction = () => {};              // Named export
export default myFunction;                       // Default export

ESM이 Tree Shaking에 유리한 이유:

// ESM — 정적 분석 가능 (빌드 타임에 import 관계 파악)
import { specificUtil } from "./utils"; // 번들러가 "specificUtil만 필요" 파악 가능
 
// CJS — 동적이라 분석 불가
const utils = require("./utils");
const fn = utils[dynamicKey]; // 런타임에 결정 → 번들러가 뭘 쓸지 모름 → 전부 포함

📤 4. ESM Export 패턴

Named Export

영철이가 공통 유틸리티 함수들을 모아둔 파일을 만들 때의 일입니다. 여러 번 사용할 함수들이므로 명확한 이름표를 달아 내보내는 것이 유리합니다. 이를 Named Export라고 부릅니다.

// utils/postHelpers.js
 
// Named export — 이름을 명시
export function formatDate(dateString) {
  return new Date(dateString).toLocaleDateString("ko-KR");
}
 
export const POST_LIMIT = 10;
 
export class PostValidator {
  validate(post) { /* ... */ }
}
 
// 한 번에 묶어서 export
function fetchPost() { /* ... */ }
function createPost() { /* ... */ }
 
export { fetchPost, createPost };
 
// 이름 바꿔서 export
export { fetchPost as getPost };

// 사용 측 — Named import
import { formatDate, POST_LIMIT } from "./utils/postHelpers";
import { formatDate as fd } from "./utils/postHelpers"; // 별칭
 
// 전체 가져오기 (Tree Shaking 불리)
import * as PostHelpers from "./utils/postHelpers";
PostHelpers.formatDate("2026-03-05");

Default Export

반면, 화면을 구성하는 리액트 컴포넌트처럼 한 파일이 뚜렷한 메인 단일 역할을 담당할 때는 파일의 기본값을 지정해 주는 방식이 자연스럽습니다. 이를 Default Export라고 부릅니다.

// components/PostCard.jsx
 
// Default export — 파일당 하나만
export default function PostCard({ title, author }) {
  return <div>{title} by {author}</div>;
}
 
// 또는
const PostCard = ({ title, author }) => (
  <div>{title} by {author}</div>
);
export default PostCard;

// 사용 측 — 이름을 자유롭게 지정 가능
import PostCard from "./components/PostCard";
import Card from "./components/PostCard"; // 같은 것, 이름 자유롭게

Named vs Default 언제 선택?

영철이는 매번 모듈을 내보낼 때마다 어떤 방식을 선택해야 할지 고민했습니다. 영호 리드 님은 팀의 일관성을 위해 다음과 같은 실무적인 가이드라인을 제안했습니다.

// ✅ Named export를 써야 할 때
// 1. 유틸 함수 모음 (여러 개 export)
export const formatDate = (d) => { ... };
export const formatViews = (n) => { ... };
export const truncateText = (text, limit) => { ... };
 
// 2. 상수/타입 export
export const API_BASE_URL = "...";
export type PostStatus = "draft" | "published";
 
// ✅ Default export를 써야 할 때
// React 컴포넌트 (파일당 하나의 주요 컴포넌트)
export default function PostList() { ... }
 
// 🚫 혼용 시 주의 (가능하지만 혼란스러울 수 있음)
export default function PostCard() { ... }
export const POST_CARD_VARIANTS = ["minimal", "full"];
// → 이 패턴은 괜찮음. 주요 컴포넌트 + 관련 상수

업계 권장사항: 라이브러리 코드는 Named export 위주 (Tree Shaking 유리). React 컴포넌트는 Default export 관행.

⚡ 5. 동적 import — 코드 스플리팅

영철이가 게시글 에디터 컴포넌트를 추가하고 나서 초기 번들이 300KB 가까이 불어났다. 영호 리드 님이 번들 분석 결과를 보여주며 말했다: "에디터는 실제로 쓸 때 로드하면 돼요. 동적 import() 써봤어요?" 그날부터 영철이는 코드 스플리팅을 배웠다.

// 정적 import — 앱 시작 시 무조건 로드
import HeavyEditor from "./components/HeavyEditor"; // 초기 번들에 포함
 
// ✅ 동적 import — 필요한 시점에만 로드
async function openEditor() {
  const { default: HeavyEditor } = await import("./components/HeavyEditor");
  // HeavyEditor 사용
}
 
// React에서의 코드 스플리팅 (React.lazy + Suspense)
import React, { lazy, Suspense } from "react";
 
const HeavyEditor = lazy(() => import("./components/HeavyEditor"));
// HeavyEditor가 렌더링될 때 청크를 로드
 
function App() {
  return (
    <Suspense fallback={<div>에디터 로딩 중...</div>}>
      <HeavyEditor />
    </Suspense>
  );
}
 
// 라우트 기반 코드 스플리팅 (Next.js)
// Next.js는 페이지 파일을 자동으로 코드 스플리팅
 
// 조건부 로드 — 무거운 라이브러리를 특정 액션 시에만
async function handleExport() {
  // 엑셀 내보내기 버튼 클릭 시에만 xlsx 라이브러리 로드
  const { default: xlsx } = await import("xlsx");
  const wb = xlsx.utils.book_new();
  // ...
}

🌳 6. Tree Shaking 친화적 코드 작성

코드 스플리팅을 적용하더라도, 애초에 모듈을 잘못 불러오면 번들러가 불필요한 코드까지 함께 짐을 꾸리게 됩니다. 영숙 님이 "페이지 렌더링이 조금 무겁게 느껴져요"라고 피드백했을 때, 영호 리드가 가장 먼저 점검을 지시한 패턴들입니다.

// ❌ Barrel export — Tree Shaking 방해
// utils/index.js
export { formatDate } from "./formatDate";
export { fetchPost } from "./fetchPost";
export { createPost } from "./createPost";
export { HeavyPostEditor } from "./HeavyPostEditor"; // 무거운 컴포넌트
 
// 사용 측
import { formatDate } from "./utils"; // formatDate만 쓰는데...
// 번들러에 따라 index.js 전체를 분석해야 하므로 HeavyPostEditor도 포함될 수 있음
 
// ✅ 직접 경로 import
import { formatDate } from "./utils/formatDate"; // 정확하게 이 파일만
 
// ✅ sideEffects 설정 (package.json)
// {
//   "sideEffects": false  // 모든 파일이 순수함 → 번들러가 적극적으로 Tree Shaking
// }
 
// ✅ 라이브러리 import 방식 비교
// ❌ 전체 import — lodash 전체가 번들에 포함 (70KB+)
import _ from "lodash";
_.debounce(fn, 300);
 
// ✅ 개별 함수 import — debounce만 포함
import debounce from "lodash/debounce";
debounce(fn, 300);
 
// ✅ ESM 지원 라이브러리 사용 (lodash-es)
import { debounce } from "lodash-es"; // ESM → Tree Shaking 가능

📝 마무리 퀴즈

Q1. ESM과 CJS의 가장 핵심적인 차이점을 설명하라.

✅ 정답: ESM은 정적(Static) 으로 파싱 시 모듈 관계가 결정되고, CJS는 동적(Dynamic) 으로 런타임에 require()가 실행되며 결정된다.

💡 상세 해설:

• ESM: import 경로는 정적 문자열이어야 하며, 번들러가 빌드 시 전체 의존 관계를 파악 → Tree Shaking 가능
• CJS: require(variable)처럼 동적 경로 가능, 런타임에 결정 → 번들러가 사전에 분석 불가
• Node.js에서 ESM을 사용하려면: package.json에 "type": "module" 설정하거나 .mjs 확장자 사용
• 📌 핵심 기억법: "CJS는 런타임, ESM은 빌드타임. 이 차이가 Tree Shaking의 가능 여부를 결정한다."

Q2. Named export와 Default export를 각각 언제 사용하는 것이 적절한가?

✅ 정답:

• Named export: 유틸 함수 모음, 상수, 타입 등 한 파일에 여러 항목 을 export할 때
• Default export: React 컴포넌트 등 파일당 주요 항목 하나 를 export할 때

💡 상세 해설:

• Named export의 장점: 명시적, 자동완성 친화적, Tree Shaking에 유리
• Default export의 장점: import 시 이름 자유롭게 지정 가능 (리네이밍 없이)
• Default export의 단점: 파일명과 import 이름이 달라질 수 있어 추적 어려움 (ESLint 규칙으로 강제하는 팀도 있음)
• 많은 라이브러리(예: date-fns, lodash-es)가 Named export 위주인 이유: Tree Shaking 최적화
• 📌 핵심 기억법: "유틸은 Named, 컴포넌트는 Default. 단, 팀 컨벤션이 우선이다."

Q3. 영철이의 테스트 타임 — 시니어 면접 도전

면접관: "배럴(Barrel) export 패턴이란 무엇이고, 번들 크기에 어떤 영향을 줄 수 있나요? 어떻게 이 문제를 해결하나요?"

✅ 정답: Barrel export는 index.js에서 여러 모듈을 re-export하는 패턴으로, 편리하지만 Tree Shaking이 제대로 동작하지 않는 번들러에서 불필요한 코드까지 포함될 수 있다. 직접 경로 import 또는 번들러 설정으로 완화한다.

💡 상세 해설:

• Barrel export란: utils/index.js에서 export { A } from './a'; export { B } from './b';처럼 한 곳에 모아두는 패턴. import 경로가 짧아 편리하다.
• 문제점: 일부 번들러 + 일부 설정에서 index.js를 처리하며 B를 쓰지 않아도 B 모듈의 사이드 이펙트가 포함될 수 있다.
• 해결책:
  1. 직접 경로 import: import { A } from "./utils/a" (가장 확실)
  2. package.json에 "sideEffects": false 설정
  3. Vite, Rollup, webpack 최신 버전은 ESM barrel export를 잘 처리
• 실무 트레이드오프: 큰 앱에서 barrel export 남용은 초기 모듈 분석 시간에 영향을 줄 수 있습니다. Next.js 팀도 barrel export 최소화를 권고하고 있습니다.
• 📌 핵심 기억법: "Barrel 패턴은 편리하지만, 자칫하면 번들에 불필요한 소스 코드를 포함하게 만들 수 있습니다. 성능이 특히 중요한 곳에서는 직접 경로 import를 한 번 더 고려해 보세요."

🐣 영철이의 퇴근 일기

오늘은 진짜 "이게 다 연결되는구나" 하는 느낌이 들었다. 왜 import와 require가 섞여있는지, 왜 lodash-es가 따로 있는지, 왜 번들 분석할 때 안 쓰는 코드가 포함되는지 — 모두 ESM vs CJS 차이에서 비롯됐다는 걸 이제 이해한다.

Tree Shaking이 마법이 아니라 "정적 분석 가능한 ESM이기 때문에" 가능한 거라는 것도 새로 알았다. 그동안 당연하게 쓰던 import가 이렇게 깊은 배경이 있었다니.

💡 오늘의 교훈: "ESM은 번들러에게 '이 코드의 의존성 지도'를 미리 보여준다. 지도가 있으니 안 쓰는 코드를 솎아낼 수 있다. CJS는 런타임에야 길을 알아서 미리 솎아낼 수 없다."

이번 주가 거의 다 됐다. 다음 주에는 에러 처리, Map/Set 챕터가 남아있는데, 이것도 기대된다. 주말에 오늘 배운 모듈 시스템 정리해서 스터디 공유 문서에 올려야지. 오늘도 수고했다, 나 자신!

🔗 더 알아보기

• MDN — Modules guide
• Node.js — ESM 공식 문서
• Vite — Library Mode & Tree Shaking