fix(build): change output extension from .mjs to .js for Next.js 13 compatibility

[ywkim]

요약

Next.js 13.x 버전의 webpack CJS/ESM interop 버그로 인해 .mjs 빌드 파일에서 next/image import가 실패하는 문제를 .js 확장자로 회피.

목적

버그 성격: Next.js 13.5.6~14.0.4의 webpack 버그로, .mjs 파일을 강제로 순수 ESM으로 처리하여 CJS 모듈(next/image)과의 interop이 실패함. 14.1.0에서 수정되었으나, 하위 호환성을 위해 .js 확장자를 사용.

기술적 배경:

• .mjs와 .js + "type": "module" 모두 Node.js 표준 ESM 방식
• 둘 다 올바른 선택이며, .mjs가 "잘못된" 것이 아님
• Next.js 13.x의 버그로 인해 .mjs만 작동하지 않았음

주요 개선 사항

🔧 빌드 설정 변경

• Vite 빌드 출력: .mjs → .js 확장자 (Next.js 13.x 호환성)
• ESM-only 빌드: CJS 빌드 제거, "type": "module"만 유지
• package.json exports: 경로를 .js로 업데이트

✅ 호환성 개선

• Next.js 13.5.6에서 next/image 정상 동작 확인
• Next.js 14.0.x까지 호환성 확보
• webpack CJS/ESM interop 버그 회피

📦 package.json 변경

- "module": "dist/index.mjs",
+ "module": "dist/index.js",
  "exports": {
    ".": {
-     "import": "./dist/index.mjs",
-     "require": "./dist/index.js"
+     "import": "./dist/index.js"
    }
  }

⚙️ vite.config.ts 변경

lib: {
-  formats: ["es", "cjs"],
-  fileName: (format, entryName) =>
-    `${entryName}.${format === "es" ? "mjs" : "js"}`,
+  formats: ["es"],
+  fileName: () => "[name].js",
}

Next.js 버전별 호환성 검증

테스트 결과

Next.js 버전	.mjs 빌드	.js 빌드	비고
13.5.6	❌ Element type is invalid	✅ 정상 동작	webpack 버그
13.5.7	❌ Element type is invalid	✅ 정상 동작	webpack 버그
14.0.0	❌ Element type is invalid	✅ 정상 동작	webpack 버그
14.0.4	❌ Element type is invalid	✅ 정상 동작	webpack 버그
14.1.0+	✅ 수정됨	✅ 정상 동작	버그 수정

Next.js 14.1.0 버그 수정사항

해결 PR: vercel/next.js#60169 - Fix emitting ESM swc helpers for 3rd parties CJS libs in bundle

버그 원인:

• PR #58967에서 모든 모듈을 type: 'es6'로 강제 설정
• CJS 외부 라이브러리(next/image 등)도 ESM으로 잘못 처리
• swc가 modern syntax 컴파일 시 ESM 스타일 helpers를 emit → CJS 호환성 깨짐

수정 방법:

• auto-cjs swc plugin 버그 수정 (@kdy1)
• 기본 모듈 타입 감지 복원
• 파일이 CJS인지 ESM인지 정확히 판별하여 올바른 helpers emit

핵심 변경 (packages/next/src/build/swc/options.ts):

// BEFORE (14.0.4): 강제로 es6 모듈 타입 지정
function getModuleOptions(esm: boolean | undefined = false) {
  return esm ? { module: { type: 'es6' } } : {}
}

// AFTER (14.1.0): 파일별로 적절한 모듈 타입 감지
function shouldOutputCommonJs(filename: string) {
  return isCommonJSFile(filename) || nextDistPath.test(filename)
}
const moduleResolutionConfig = shouldOutputCommonJs(filename)
  ? { module: { type: 'commonjs' } }
  : {}  // 기본값 사용 (auto-cjs 플러그인이 자동 감지)

결론:

• Next.js 14.1.0+에서는 .mjs 파일도 정상 동작
• .js 선택은 Next.js 13.x~14.0.x 하위 호환성을 위한 실용적 결정
• .mjs와 .js 모두 표준이며, 둘 중 하나가 더 "올바른" 것은 아님

구조 변경

변경된 파일:

frontend/
├── .gitignore         # *.tgz 추가
├── package.json       # exports 경로 .js로 변경
├── package-lock.json  # peer dependency 정리
└── vite.config.ts     # ESM-only .js 빌드

테스트 체크리스트

• Next.js 13.5.6 환경에서 빌드 성공
• next/image 컴포넌트 정상 렌더링
• URL 미리보기 카드 표시 확인
• "Element type is invalid" 에러 없음
• Next.js 14.1.0에서 버그 수정 확인
• 릴리스 노트 및 관련 PR 검증
• Node.js ESM 표준 확인 (.mjs와 .js 모두 유효)

개선 효과

기존 (.mjs + Next.js 13.x ~ 14.0.x):

• Next.js webpack 버그로 .mjs를 강제 순수 ESM 처리
• CJS 모듈(next/image)과의 interop 실패
• import 시 빈 객체 반환 → 렌더링 에러

개선 후 (.js + "type": "module"):

• .js + "type": "module"로 ESM 명시 (표준 방식)
• webpack이 CJS interop 정상 처리
• Next.js 13.x ~ 14.x 모두 호환

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

이 PR은 Next.js 13과의 호환성을 위해 빌드 결과물의 확장자를 .mjs에서 .js로 변경하고 ESM 전용 패키지로 전환하는 것을 목표로 하고 있습니다. 전반적인 변경 방향은 좋지만, 빌드 실패나 런타임 오류를 유발할 수 있는 두 가지 치명적인 문제를 발견했습니다. 첫째, package.json에 "type": "module" 필드가 누락되어 Node.js가 .js 파일을 ESM으로 인식하지 못할 수 있습니다. 둘째, vite.config.ts의 fileName 함수가 잘못 설정되어 빌드 시 파일 이름이 충돌할 가능성이 높습니다. 각 문제에 대한 수정 제안을 코드 리뷰 댓글로 남겼으니 확인 부탁드립니다.

[github-actions]

🎉 This PR is included in version 1.14.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀