[JavaScript]export default vs named export, 언제 어떻게 써야 할까?

Next.js로 프로젝트를 하다 보면 export default를 자주 마주치게 된다. 페이지 컴포넌트마다 빠지지 않고 등장하는데, 왜 하필 default일까? named export와는 뭐가 다르고, 어떤 상황에서 어떤 걸 써야 할까? 이번 글에서는 둘의 차이를 정리하고, 실무에서의 판단 기준까지 다뤄보려 한다.

기술 개념

📋 이 글에서 다루는 내용

• default export / named export
• 왜 두 가지 방식이 존재하는지, 각각 어떤 문제를 해결하는지
• Next.js에서 default export가 필수인 이유와 실무 판단 기준

1. 개념이란?

JavaScript의 ES Modules에서는 모듈을 내보내는 방식이 두 가지 있다. default export는 파일에서 하나의 대표 값을 내보내는 방식이고, named export는 이름을 지정해서 여러 개를 내보내는 방식이다.

⚡ 핵심 포인트
- default export는 import할 때 이름을 자유롭게 지을 수 있고, named export는 내보낸 이름을 그대로 사용해야 한다.

2. 왜 필요한가?

옛날 JavaScript는 <script> 태그로 파일을 여러 개 불러오면 전부 하나의 공간을 공유했다.

<script src="a.js"></script>  <!-- var name = "영희"; -->
<script src="b.js"></script>  <!-- var name = "철수"; -->

이러면 a.js에서 만든 name이 b.js의 name에 덮어씌워진다. 파일을 나눠놨는데도 변수가 충돌하는 거다. 프로젝트가 커질수록 "이 함수가 어디서 온 거지?" 추적하기도 점점 힘들어졌다.

그래서 ES Modules가 등장했다. 각 파일이 독립된 공간을 갖고, 필요한 것만 골라서 내보내고 가져오는 방식이다. 이때 내보내는 방식이 두 가지로 나뉘는데, 파일의 "대표 선수"를 하나 정해서 내보내는 게 default export, 여러 명을 이름표 붙여서 내보내는 게 named export다.

구분	default export	named export
내보내는 개수	파일당 하나	여러개 가능
import시 이름	자유롭게 지정 가능	반드시 동일한 이름 (또는 as로 별칭)
주 사용처	컴포넌트, 설정파일	유틸 함수, 상수 모음, 타입/인터페이스

유틸 함수란? 날짜 포맷, 가격 포맷처럼 프로젝트 여기저기서 반복 사용하는 도우미 함수들을 한 파일에 모아둔 것이다.
상수 모음이란? API 주소, 최대 재시도 횟수처럼 고정된 값들을 한곳에 모아둔 것이다. 여러 파일에서 직접 값을 쓰면 나중에 바꿀 때 전부 찾아다녀야 하니까, 한 파일에 모아두고 import해서 쓴다.

3. 동작 원리

1

모듈이 내보내는 값을 정의한다

// lib/axios.js
const instance = axios.create({ baseURL: 'https://api.example.com' });
export default instance;

export default는 이 파일의 대표 값을 instance로 지정한다. 내부적으로 모듈 객체의 .default 속성에 값이 할당된다.

2

 다른 파일에서 import한다javascript

import axios from './lib/axios';

default export를 가져올 때는 {} 없이 원하는 이름을 쓴다. 이때 실제로는 모듈의 .default 속성을 읽어오는 것이다.

3

프레임워크가 .default를 활용한다 (Next.js의 경우)

// Next.js 내부 동작 (대략적으로)
const PageComponent = require('pages/404').default;

Next.js는 페이지 파일에서 .default 값을 꺼내 렌더링한다. 함수 이름이 뭐든 상관없이 default로 내보낸 값만 사용한다.

 

4. 코드로 보는 예시

▸ default export

// components/ProductCard.jsx
export default function ProductCard() {
  return <div>상품 카드</div>;
}

// 가져오는 쪽 - 아무 이름이나 가능
import ProductCard from './components/ProductCard';
import Card from './components/ProductCard';       // 같은 컴포넌트

▸ named export

// utils.js
export function formatDate(date) {
  return `${date.getFullYear()}년 ${date.getMonth() + 1}월`;
}

export function formatPrice(price) {
  return price.toLocaleString() + '원';  // 1000 → "1,000원"
}

// constants.js 
export const API_URL = 'https://api.example.com';
export const MAX_RETRY = 3;
export const PAGE_SIZE = 20;

// 가져오는 쪽 - 반드시 같은 이름
import { formatDate, formatPrice } from './utils';
import { API_URL, PAGE_SIZE } from './constants';

▸ 실전 활용 - default + named를 함께 쓰는 패턴

컴포넌트는 파일의 "대표"니까 default, 타입은 부속품이니까 named로 내보낸다.

// components/ProductCard.tsx
export default function ProductCard({ title, price }: ProductCardProps) {
  return (
    <div>
      <h2>{title}</h2>
      <span>{price}원</span>
    </div>
  );
}

// 타입이나 인터페이스는 named export
export type ProductCardProps = {
  title: string;
  price: number;
};

// 가져오는 쪽
import ProductCard, { ProductCardProps } from './components/ProductCard';

5. 주의할 점

🚨 default export는 팀 내 이름 불일치를 유발할 수 있다

같은 모듈을 import하면서 팀원마다 다른 이름을 쓰면 코드 검색과 리팩토링이 어려워진다.

// 팀원 A
import axios from './lib/axios';
// 팀원 B
import api from './lib/axios';
// 팀원 C
import httpClient from './lib/axios';

named export를 쓰면 이름이 강제되므로 이런 문제를 방지할 수 있다.

🚨 주의 2: 프레임워크가 default export를 요구하는지 반드시 확인하자

Next.js 페이지에서 named export만 하면 컴포넌트를 인식하지 못한다. 새로운 프레임워크를 사용할 때는 공식 문서를 먼저 확인하거나, 에러 메시지를 통해 규칙을 파악하자.

Error: The default export is not a React Component in page: "/about"

대표적으로 default export를 요구하는 것들: Next.js 페이지, React.lazy(), Storybook stories

6. 정리

✅ 정리하면

• default export는 파일의 대표 값을 하나 내보낼 때, named export는 여러 개를 내보낼 때 사용한다
• Next.js 페이지처럼 프레임워크가 요구하는 경우 default export는 선택이 아니라 규칙이다
• 타입(type, interface)이나 유틸 함수, 상수처럼 한 파일에 여러 개가 들어가는 경우는 named export가 자연스럽다
• 실무에서는 named export를 기본으로 쓰고, 프레임워크 요구사항이나 파일 역할이 명확히 하나일 때만 default export를 쓰는 팀이 많다
• 새로운 도구를 쓸 때는 공식 문서를 먼저 읽는 습관이 가장 중요하다

🔗 참고 자료

• MDN - export
• MDN - import
• Next.js - Pages