Next js Lottie 사용할때 Document is not defined Build 에러

프로젝트를 진행 하던 중 멀쩡하게 로컬에선 잘 돌아가던 프로젝트가 build가 안되는 문제가 발생했다.

모든 라우트에서 에러가 발생하는 것을 확인

 

처음에는 모든 paths에서 다 에러가 난다고 해서, 의존성 패키지 혹은 옛날 브랜치부터 하나하나 다 까보면서 
의존성 삭제 -> 설치 -> 빌드 를 반복했다.

CI / CD의 중요성을 너무나도 절실히 느꼈다.

 

빌드가 정상적으로 되는 브랜치와 그 다음 작업된 브랜치를 확인해 보니, 

App Router의 기본적인 Loading, Error 같은 페이지들을 추가한 뒤로 안되고 있는 것을 확인했다.

 

이때 처음 생각했던 문제는 해당 페이지들을 작업하면서 사용한 twin.macro 혹은 "use client"의 부재 문제라고 생각했다.

 

하지만 해당 문제를 모두 해결했음에도 빌드 에러는 계속해서 났고, error, loading, 404 페이지들을 하나하나 삭제해보면서 빌드해보니 
loading페이지가 삭제되었을때 빌드가 정상적으로 되는 것을 확인 할 수 있었다.

 

문제 범위를 좁혀서 확인해보니, Lottie에 문제가 있었다.

https://lottiefiles.com/kr/what-is-lottie

Lottie 애니메이션은 무엇일까요? - 로티파일즈

 

기존 방식에서는 lottie-web을 사용하면서 

  React.useEffect(() => {
    if (!wrapperRef.current) return;
    lottie.loadAnimation({
      container: wrapperRef.current,
      animationData: loading,
      renderer: 'svg',
      loop: true,
      autoplay: true,
    });
    return () => {
      lottie.destroy();
    };
  }, [wrapperRef]);

 

이런 방식으로 UseEffect내에 lottie animation 옵션들을 관리해 줬었다.

 

이랬을때 로컬에서는 실행하였을때 브라우저에서 document 객체를 항상 제공해주지만,

빌드할때는 SSR 단계에서 lottie에서 사용하는 document 객체를 참조하면 document is not defined 에러가 나는 것 으로 추측된다..!

 

해당 문제를 알게 되었으니, Lottie를 SSR로 사용하지 않기 위하여 Next/dynamic을 사용해 주었다.

'use client';
import React from 'react';
import tw from 'twin.macro';
import loading from '../assets/lottie/loading-circle.json';
import dynamic from 'next/dynamic';

const Loading = () => {
  const DynamicLottie = dynamic(() => import('lottie-react'), { ssr: false });

  return (
    <Wrapper>
      <DynamicLottie
        animationData={loading}
        style={{ width: '100px', height: '100px' }}
      />
    </Wrapper>
  );
};

 

해당 방식으로 dynamic으로 lottie-react를 import해오고, ssr 옵션을 false로 해주니 정상적으로 build가 되는 것을 확인 할 수 있었다.

빌드 성공!!

 

- Next js에서 Lottie를 쓸때는 꼭 ssr 옵션을 꺼주자

- 해당 문제를 해결하면서, 다른 팀원은 Node 20버전을 사용하고, 나는 Node 22버전을 사용하고 있는 상황에서 20 버전에서는 빌드가 정상적으로 되고 있었다, 해당 이슈는 정확하게 찾지 못해서 다음에 또 알아보기로,,,,