Next.js(14버전)- SSE 실시간 알림 구현

🏷️들어가며 

해당 글은 "next": "14.2.6" 버전을 바탕으로 한 프로젝트입니다. 
SSE는 HTTP 표준 기술 중 하나이므로 특정 버전이 존재하지 않습니다. 

 

 

❓SSE를 선택한 이유는?

우리FIS아카데미에서 진행한 최총 프로젝트에서 우리의 핵심 기능은 '정산'이었다. 이때 신속한 정산을 위해 ‘정산 요청’, ‘정산 시작’, ‘정산 완료’ 등의 정보를 여행원 간 실시간으로 공유할 필요성을 느꼈고 우리는 실시간으로 서비스를 구현할 기술을 찾고 있다. 

 

SSE(Server-Sent Events) VS Polling VS WebSocket

방식	연결  방식	데이터 흐름	실시간성	서버 부하	브라우저 지원	사용 사례
SSE (Server-Sent Events)	단방향 (서버 → 클라이언트)	서버에서 클라이언트로만 데이터 전송	중간 (연결 유지)	낮음	대부분의 최신 브라우저 지원 (IE 미지원)	주가 정보, 알림 시스템, 대시보드
Polling (Short/Long)	클라이언트가 주기적으로 요청	클라이언트 → 서버 요청, 서버 응답	낮음 (지연 발생)	높음 (반복적인 요청)	모든 브라우저에서 가능	채팅, 데이터 새로고침
WebSocket	양방향 (서버 ⇄ 클라이언트)	서버와 클라이언트가 자유롭게 데이터 교환	높음 (실시간)	낮음 (연결 유지, 효율적)	대부분의 최신 브라우저 지원	실시간 게임, 채팅, 주식 거래

 

Polling은 주기적으로 서버에 요청을 보내는 방식, 리소스 낭비가 심하다고 판단, 또한 웹소켓역시 양방향 통신으로 우리가 구현할 실시간 알림에 쓰기에는 오버 스펙이라고 생각했다. 그래서 서버에서 클라이언트로 단방향 통신인 SSE를 선택해서 구현하게 되었다. 

 

++ SSE와 WebSocket의 차이 

SSE는 웹 기술이기 때문에 HTTP 프로토콜 위에서 동작한다.또한, HTTP 연결을 유지한 상태에서 재연결이나 추가 설정 없이 서버로부터 지속적인 데이터 스트림을 받을 수 있다.

반면, WebSocket은 독립적인 프로토콜을 사용하고, HTTP와는 별도의 연결을 만들어 데이터를 주고받는다.

 

SSE는 CORS(Cross-Origin Resource Sharing)을 통해 다른 도메인에서도 데이터를 수신할 수 있다. WebSocket도 동일한 도메인 간 통신을 제공하지만, 보안상의 이유로 추가 구성이 필요할 수 있다.

 

🚀 Next.js에 SSE 적용하기

Next.js에서는 서버 사이드 렌더링 지원해서 SSE API Route도 구현할 수 있다. 하지만 우리 프로젝트에서느 Spring으로 서버를 구현했기 때문에 나는 데이터를 받아오는 로직을 구현하면 됐다! 

 

우리 서비스에서는 실시간 알림 서비스를 로그인된 회원만 이용할 수 있도록 설계했다. 그래서 서버랑 SSE 연결 시 Authorization 헤더에 토큰값을 포함하여 인증된 요청만 처리되도록 구현해야했고 EventSource API는 요청을 보낼 때 커스텀 헤더를 추가할 수 없어서 event-source-polyfill라이브러리를 사용하였다.

 

문제 코드 

import { EventSourcePolyfill } from 'event-source-polyfill';
import { auth } from '@withbee/auth-config';

export const connectSSE = async (url: string, onMessage: (data: any) => void, onConnect?: () => void, onError?: (error: any) => void, token?: string) => {
  // 인증 정보 얻기
  const session = await auth();
  const accessToken = session?.user!.accessToken;
  if (!accessToken) throw new Error('Authentication required');

  // SSE 연결 설정
  const eventSource = new EventSourcePolyfill(url, {
    headers: { Authorization: `Bearer ${accessToken}` },
    heartbeatTimeout: 30000,  // 30초마다 heartbeat 체크
  });

  // 연결 성공 이벤트
  eventSource.addEventListener('connect', (event: any) => {
    if (event.data === 'SSE 연결이 완료되었습니다.') {
      onConnect?.(); // 연결 완료 콜백 호출
    }
  });

  // 메시지 수신 이벤트
  eventSource.addEventListener('message', (event: MessageEvent) => {
    onMessage(event.data); // 메시지 처리
  });

  // 에러 처리
  eventSource.onerror = (error) => {
    console.error('SSE Error:', error);
    onError?.(error); // 에러 콜백 호출
    eventSource.close(); // 연결 종료
  };

  return eventSource; // 이벤트 소스 반환
};

 

이렇게 코드를 완성한 후에 돌려봤는데 다음과 같은 에러가 떴다. 

 

headers 객체가 서버 요청 스코프 밖에서 호출됨

처음에는 무슨 소리인가 했는데  서버 컴포넌트에서는 브라우저 전용 API인 EventSource 를 사용할 수 없어서 난 에러였다!.

 

그렇다면 요청 스코프 밖에서 호출됐다는 게 무슨 말일까?

• connectSSE 함수가 'use client' 지시문 없이 작성됨
• Next.js는 이 코드를 서버 컴포넌트로 인식
• 빌드/서버 시작 시점에 이 코드가 평가됨
• 이 시점에는 실제 HTTP 요청이 없음 (= 요청 스코프 밖)
• headers 객체를 생성하려고 시도하지만 실제 요청 컨텍스트가 없어서 에러 발생

그러니깐 대강 요약해보면 브라우저 전용 api안에 header가 있는데 서버컴포넌트에서 이를 부를려고 하니깐 요청 스코프 밖에서 header객체가 호출됐다는 것이다. 

 

꼬꼬질(꼬리의 꼬리를 무는 질문 ㅎㅎ 내가 만든 용어)

그렇다면 요청 스코프는 정확히 언제 표현되는 단어일까? 

 

요청 스코프는 하나의 HTTP 요청이 시작되어 응답이 완료될 때까지의 생명주기를 가지는 실행 컨텍스트를 의미한다.  Next.js에서는 크게 세 가지 컨텍스트가 있다. 

 

서버 사이드 렌더링(SSR) 컨텍스트

// 서버에서 실행되는 코드
// headers(), cookies() 등의 API 사용 가능
export default function Page() {
  // 여기는 요청 스코프 내부
}

 

클라이언트 사이드 컨텍스트

'use client'
// 브라우저에서 실행되는 코드
// window, document 등 브라우저 API 사용 가능

 

서버 컴포넌트 빌드 타임 컨텍스트

// 빌드할 때 실행되는 코드
// 요청 스코프 밖
const config = {
  // 여기서 headers 접근 불가
}

 

해결책은 간단했다. EventSourcePolyfill이 필요로 하는 브라우저 컨텍스트가 없었고 headers 객체를 생성하려고 하지만 실제 HTTP 요청 컨텍스트가 없어 에러가 난 거기 때문에 저 컴포넌트를 클라이언트 컴포넌트로 바꿔주면 된다. 그러니깐 'use client'만 붙여주면 된다. 

 

문제 해결 코드 

'use client';
// import 생략

export default function RealTimeMsg() {
  const { data: session, status } = useSession();
  const [notifications, setNotifications] = useState<Notification[]>([]);
  const [accessToken, setAccessToken] = useState<string | null>(null);
  const [isVisible, setIsVisible] = useState(false);
  const [isAnimatingOut, setIsAnimatingOut] = useState(false);

  useEffect(() => {
    if (
      status === 'authenticated' &&
      session?.user?.accessToken &&
      !accessToken
    ) {
      setAccessToken(session.user.accessToken);
    }
  }, [session, status, accessToken]);

 useEffect(() => {
  let eventSource: EventSourcePolyfill;
  if (accessToken) {
    (async () => {
      eventSource = await connectSSE(
        `${BASE_URL}/api/notifications/stream`,
        (rawData) => {
          const parsedNotification: Notification = JSON.parse(rawData);
          setNotifications((prev) => [...prev, parsedNotification]);
          // 알림 표시 및 자동 제거 타이머 설정
        }
      );
    })();
  }
  // 클린업
  return () => {
    eventSource?.close();
  };
}, [accessToken]);

  const handleClose = () => {
    setIsAnimatingOut(true);
    setTimeout(() => {
      setIsVisible(false);
      setNotifications((prev) => prev.slice(1));
    }, 1000); // 애니메이션 시간과 맞춤
  };

  if (!isVisible || notifications.length === 0) {
    return null;
  }

  const notification = notifications[0];
  if (!notification) {
    return null;
  }

  return (
    <div className={styles.background}>
      // 생략
    </div>
  );
}

 

 

최종 화면 

 

 

 

💫마치며 

사실 서버 컴포넌트를 클라이언트 컴포넌트로 바꾸면 해결되는 문제였지만 에러 로그에서 Next.js의 SSR과 CSR의 충분한 이해가 없으면 헷갈리는 문제였기에 충분한 시간을 들여서 고민해보았다,, 그리고 그 뒤로 배포하는 과정에서 로컬에서 개발할 때는 SSE 연결이 에러 없이 잘 작동했는데 배포 후 SSE연결하는 페이지에서 502 Bad Gateway에러가 발생했었다. SSE통신을 지속적으로 연결하려면 nginx쪽에서도 따로 또 설정을 해줘야 했다. 다행히 팀원들의 도움으로 마무리를 깔끔하게 할 수 있었던 것 같다. 새로운 기술 학습해서 짜릿하다~~🪓

 

 

 

 

 

참고자료 

• https://iii.ad/7a8a43
• https://developer.mozilla.org/ko/docs/Web/API/Server-sent_events/Using_server-sent_events