Lottie-web의 Node.js v21 이상 버전 SSR 이슈

Lottie-web 라이브러리를 Node 21 이상에서 실행했을 경우 발생한 문제와 해결방안에 대해 설명합니다.

문제 상황

lottie-web이 SSR(Server Side Rendering) 환경에서 'document is not defined' 오류가 발생합니다.

// 문제가 발생하는 코드 (Node v21 이상에서 에러 발생)
import lottie from 'lottie-web'  

const handler = useCallback(async() => {
  lottie.loadAnimation()
})

이슈 원인

• Node.js v21 이상부터 발생
• lottie-web v5.13.0 에서 수정 반영 되었으나 패키지의 release 문제로 여전히 오류 발생

왜 이런 문제가 발생했을까요? lottie.js에 답이 있습니다.

이슈 상세

lottie는 클라이언트에서만 실행되도록하는 방어로직을 navigator 유무로 체크합니다.

하지만 Node.js 21부터 서버사이드에도 navigator가 추가 되었기 때문에 오류가 발생합니다.

 

아래 PR에서 논의되고 있으니 관심이 있다면 살펴보셔도 좋습니다.
https://github.com/airbnb/lottie-web/pull/3096

fix: document validation for SSR by IcaroG · Pull Request #3096 · airbnb/lottie-web

 

lottie에서 어떻게 수정 반영 했는지 알아보겠습니다.

// 기존
(typeof navigator !== 'undefined') && /* lottie 코드 */

• lottie 5.13.0 이전 버전까지는 navigator 유무로 브라우저 환경과 Node.js 환경을 구분합니다.
• Node.js v21 이전에는 서버에서 navigator 객체가 없기 때문에 옳은 조건이지만 Node.js v21 이후에는 navigator 객체가 존재하기 때문에 런타임 에러가 발생합니다.

lottie 5.13.0 부터 아래와 같이 document도 확인하는 코드가 추가되었습니다.

// Node v21 대응, lottie-web v5.13.0 이후
(typeof document !== 'undefined') && (typeof navigator !== 'undefined') && /* lottie 코드 */

 

5.13.0 버전에서 패치되었으나 release 에서 문제 발생하여 아직 반영이 안되었다고 합니다 😅

 

만일 꼭 Node21 이상을 사용해야한다면, lottie-web에서 이 문제가 해결될 때까지는 dynamic import 방식을 사용하면 오류를 피할 수 있습니다.

// dynamic import로 실행 시 오류 발생하지 않음
const handler = useCallback(async() => {
  const { default: lottie } = await import('lottie-web');
  lottie.loadAnimation()
})

 

 

실제 코드를 보고 싶다면 아래 링크에서 확인할 수 있습니다.

기존 코드

lottie-web

Node v21 대응 코드

lottie-web/build/player/lottie.js at bede03d25d232826e0c9dca1733d542d8a7754fb · airbnb/lottie-web