💥 Next.js에서 styled-components 설정 시 발생한 Babel 에러 해결기

✅ 상황

오늘 프로젝트에서 styled-components를 Next.js 15 환경에서 사용하려고 했습니다.
SSR도 적용하고 싶어서 공식 문서를 보고 babel.config.js에 babel-plugin-styled-components를 설정했습니다.

// babel.config.js
module.exports = {
  presets: ['next/babel'],
  plugins: [['styled-components', { ssr: true, displayName: true }]],
};

그런데...

❗ 문제 발생

Error: Cannot require() ES Module babel.config.js in a cycle
ReferenceError: module is not defined

• styled-components를 적용하자마자 Next.js dev 서버가 깨지기 시작했습니다.

• Babel 설정을 못 불러온다거나, module이 undefined라는 오류가 반복 발생했고,

• .next/fallback-build-manifest.json도 없다고 하며 컴파일도 실패했습니다.

🔍 원인 분석

• babel.config.js는 CommonJS 형식으로 작성되어야 하지만,
  내 package.json에 "type": "module"이 있었기 때문에 Next.js는 이 파일을 ESM으로 인식하게 됨.

• .cjs 확장자를 써도 Next.js 15에서는 babel.config.cjs를 아예 지원하지 않음.

• babel-plugin-styled-components 패키지를 설치하지 않은 상태에서 Babel 플러그인을 쓰면 또 에러 발생.

→ 이래저래 꼬이기 시작했습니다.

🔁 시도한 해결 방법

1. "type": "module" 제거

2. babel.config.js에서 CommonJS(module.exports) 명확히 지정

3. .cjs로 확장자 바꿔보기

4. cross-env 설치해서 NODE_OPTIONS 전달

5. babel-plugin-styled-components 직접 설치

하지만 Next.js 15에서는 Babel 로더가 .cjs, .mjs 파일 자체를 아예 거부하기 때문에
결국 Babel 설정 방식으로는 styled-components를 안정적으로 적용하기 어려웠습니다.

✅ 최종 해결 방법

Next.js 12 이상에서는 사실 styled-components를 Babel 없이도 설정할 수 있다는 걸 알게 됐습니다.

📦 해결 절차

1. babel.config.js 완전 삭제

2. next.config.js 새로 생성 후 아래 설정 추가

/** @type {import('next').NextConfig} */
const nextConfig = {
  compiler: {
    styledComponents: true,
  },
};

module.exports = nextConfig;

3. package.json에서 "type": "module" 제거

4. eslint.config.js에서 globals: globals.node로 수정해 ESLint 오류 해결

5. dev 스크립트는 기본 유지 ("dev": "next dev")

🚀 결과

• styled-components SSR 및 displayName 적용됨

• hydration mismatch 해결

• Babel 관련 에러 사라짐

• ESLint 경고도 정리됨

💡 배운 점

• Next.js 12 이상에서는 Babel 없이도 styled-components의 SSR 기능을 지원하므로 compiler.styledComponents: true 설정만으로 충분함

• "type": "module"을 사용할 경우 Babel 설정은 더 복잡해지므로 명확한 기준으로 CommonJS / ESM 구분 필요

• Babel 설정은 꼭 필요한 경우가 아니면 피하는 것도 유지보수에 좋음

styled-components를 Next.js에서 쓸 땐 먼저 next.config.js에서 compiler.styledComponents를 켜는 방식부터 시도해보는 게 훨씬 안전하다는 걸 배웠다!