📚 NextJS 환경에서, 코드엔 createContext가 없는데, createContext only works in Client Components.같은 에러가 나는 이유 및 해결 과정 - codesquad-masters2025-team01/issue-tracker GitHub Wiki

• 초기 세팅을 얼추 마무리하고 앱을 돌려봤는데, createContext only works in Client Components.같은 에러가 난다.

• "use client" 명시자를 달라고 하는데, 근데 내 코드엔 createContext가 없는데..?

에러메세지

TypeError: createContext only works in Client Components. Add the "use client" directive at the top of the file to use it. Read more: 
https://nextjs.org/docs/messages/context-in-server-component
    at eval (webpack-internal:///(rsc)/./node_modules/@emotion/react/dist/emotion-element-782f682d.development.esm.js:36:77)
    at <unknown> (rsc)/./node_modules/@emotion/react/dist/emotion-element-782f682d.development.esm.js 
(/Users/sangyoonlee1231/Desktop/codeSquad/groupProject/issueTracker/issue-tracker-main/frontend/.next/server/vendor-chunks/@emotion.js:70:1)
    at ... (이하 생략)

• @emotion/react 내부 컴포넌트(예: <Global>, <ThemeProvider>)는 React.createContext를 사용한다고 한다.
  그런데 이를 app/layout.tsx(Server Component) 안에서 바로 import해서 사용하면 서버 렌더링 단계에서 createContext가 실행돼 버리고,
  Next JS가 “createContext는 클라이언트 컴포넌트에서만 됩니다”라며 에러를 터뜨린다.

• “코드에 createContext가 없는데?” → 직접 호출한 적이 없어도
  import { Global } from '@emotion/react' 같은 코드가 있으면
  → @emotion/react 내부에서 createContext를 쓴다고 한다.

• 즉, NextJS와 Emotion을 같이 사용했을 때 발생할 수 있는 에러

“왜 'use client' 를 붙여야 할까?”
아래 4단계만 기억하면 오류의 원인을 바로 알 수 있어요!

const Box = styled.div`
  color: red;
  padding: 8px;
`;

• 이 코드는 JS 객체 → 문자열로 변환 준비를 해둡니다.
• (선택) Babel 플러그인을 쓰면 정적인 부분은 미리 계산해 속도가 빨라져요.

렌더링이 시작되면 Emotion이:

1. 스타일을 한 줄짜리 문자열로 만듭니다. (color:red;padding:8px;)
2. 같은 문자열이 또 나오면 재활용하기 위해 해시(css-1a2b3c)를 붙여요.

같은 스타일 = 같은 해시 → DOM에 한 번만 넣습니다.

• 개발 모드: <style> 태그에 그대로 문자열 삽입
• 배포 모드: 더 빠른 insertRule() API 사용

• Node 환경에서 미리 문자열을 뽑아 <style data-emotion> 태그를 HTML에 넣어 줍니다.
• 브라우저는 이 태그를 보고 다시 렌더링하지 않아도 바로 스타일이 적용!

• Emotion 내부는 React Context(=createContext) 로 테마 등을 관리합니다.
• Server Component(기본) 안에서 Emotion 컴포넌트를 바로 쓰면
  → 서버에서 createContext()가 호출되어 위 오류가 나요.

1. Provider 컴포넌트를 하나 만든 후
   그 파일 맨 위에 'use client'를 붙인다.
2. app/layout.tsx 같은 Server Component에서

   <EmotionProvider> … </EmotionProvider>

   로 감싸면 끝!

즉 Server 쪽은 HTML만, Client 쪽은 스타일 & 상태 관리를 담당하게 나누는 것이 포인트.

• 정적 스타일은 컴포넌트 밖 변수로 선언 → 렌더마다 해시 재계산 ❌
• Babel 플러그인 사용 → 정적 CSS를 컴파일 타임에 처리
• 전역 Provider 하나만 'use client' → 번들 사이즈 최소화

2025‑05‑14 기준 · Emotion v11 · Next.js 14

@emotion/style를 사용하는 곳에 'use client'를 상단에 추가하여 Client Component로 지정해주면 된다.

“styled를 import한다 = 그 파일에서 React Context가 즉시 필요하다”
따라서 서버에서 실행될 가능성이 있는 파일이라면 'use client' 없이 @emotion/styled를 사용하면 오류가 납니다.
Client 경계를 명확히 나누고 필요한 곳에만 'use client'를 추가하는 것이 베스트

• 개인 소감: NextJS와 Emotion은 서로 그리 어울리진 않은 것 같다..