Next.js에서 WebSocket 연결 오류 해결하기 (서버와 클라이언트 컴포넌트 구분 포함)

 

Next.js WebSocket 오류 해결법 (use client 잊지 마세요!)

Next.js를 사용해 WebSocket을 구현하다 보면 다음과 같은 오류 메시지를 마주칠 수 있습니다.

Error: Attempted to call the default export from <hook>, but it's on the client.

❓ 이 오류의 원인은?

Next.js에서는 서버 컴포넌트와 클라이언트 컴포넌트를 구분합니다.
WebSocket처럼 브라우저 API를 사용하는 코드는 반드시 클라이언트 컴포넌트에서 실행되어야 하죠.

✅ 해결 방법

"use client" 지시어를 가장 위에 추가하세요!

"use client";

import { useEffect } from "react";

export default function useNotifySocket(onMessage) {
  useEffect(() => {
    const socket = new WebSocket("ws://yourserver.com/ws");

    socket.onmessage = (e) => {
      onMessage?.(e.data);
    };

    return () => socket.close();
  }, [onMessage]);
}

위 훅을 사용하는 컴포넌트에서도 "use client" 선언이 필요합니다.

🧠 추가 팁

• WebSocket URL은 ws:// 또는 wss://로 시작해야 해요.
• 보안 연결을 원하면 wss로 사용하세요 (HTTPS 기반).
• 컴포넌트가 서버에서 렌더링되면 WebSocket은 작동하지 않습니다.

Next.js WebSocket 오류 예시 화면

📌 마무리

Next.js에서 WebSocket을 안전하게 사용하려면 클라이언트 전용 hook으로 분리하고, "use client"를 잊지 마세요!
이 팁들이 여러분의 실무 개발에 도움이 되기를 바랍니다.

👉 더 많은 Next.js 팁은 블로그 메인에서 확인하세요!