본 문서는 Framer를 배우는 국내 사용자들이 한글 자료의 부족으로 겪는 어려움을 해결하고자, 공식 블로그의 내용을 한국어로 번역하고 실무에 유용한 정보를 추가했습니다. 프레이머를 사용하는 여러분께 작게나마 도움이 되길 바랍니다.

최적화 문제가 발생하는 이유

Framer는 모든 디바이스에서의 성능과 호환성을 높이기 위해 페이지를 서버에서 미리 렌더링(pre-rendering)합니다. 그러나 이 과정에서 다음과 같은 제약이 있습니다.

• window, document, navigator 같은 브라우저 전용 API는 서버에서는 사용할 수 없습니다. 서버는 브라우저 환경이 아니기 때문입니다.

• 이처럼 브라우저 API에 의존하는 커스텀 코드는 미리 렌더링 중 오류를 발생시킬 수 있습니다.

브라우저 전용 API 사용을 피하세요

렌더링 시점에 브라우저 API에 의존하지 않는 JavaScript를 작성해보세요. 예를 들어, window.innerWidth를 사용하기보다는 CSS 미디어 쿼리를 활용해 반응형 레이아웃을 구현하는 것이 좋습니다.

jsx
// ❌️ 잘못된 예시: 최적화 문제 발생
export function Component() {
  const windowWidth = window.innerWidth

  return windowWidth < 768 ? <MobileVideo /> : <DesktopVideo />
}

// ✅ 올바른 예시: 최적화 문제 없음
function Component() {
  return <>
    <style>{`
      .my-component-video-mobile { display: block }
      .my-component-video-desktop { display: none }
        
      @media (min-width: 768px) {
        .my-component-video-mobile { display: none }
        .my-component-video-desktop { display: block }
      }
    `}</style>
    <div className="my-component-video-mobile"><MobileVideo /></div>
    <div className="my-component-video-desktop"><DesktopVideo /></div>
  </>
}

useEffect 안에 브라우저 API를 넣으세요

브라우저 API 사용이 꼭 필요한 경우에는 useEffect 내부에 넣는 것을 추천합니다. useEffect는 페이지가 브라우저에서 로드된 후 실행되므로, 서버 렌더링 중에는 호출되지 않아 최적화 오류를 방지할 수 있습니다.

jsx
// ❌️ 잘못된 예시: 최적화 문제 발생
function Component() {
  window.gtag("event", "component_rendered")

  return <div>Hello!</div>
}

// ✅ 올바른 예시: 최적화 문제 없음
function Component() {
  useEffect(() => {
    window.gtag("event", "component_rendered")
  }, [])

  return <div>Hello!</div>
}

브라우저 의존 데이터를 위한 플레이스홀더 사용

document.cookie나 navigator.language처럼 브라우저에서만 얻을 수 있는 정보가 필요한 경우 다음과 같은 방법을 사용해보세요:

1. 서버 렌더링 시에는 플레이스홀더만 보여줍니다.

2. 페이지가 완전히 로드되면, 해당 데이터를 기반으로 컴포넌트를 업데이트합니다.

예: framer-optim-1.jsx

최적화에서 제외하는 방법

불가피한 경우, 해당 컴포넌트를 최적화 대상에서 제외(opt-out) 할 수 있습니다:

• 서버 측 로직을 사용해 미리 렌더링을 건너뜁니다.

주의사항

• 해당 컴포넌트의 내용은 검색 엔진에 노출되지 않습니다.

• 전체 페이지가 로드된 후에만 표시됩니다.

• 사용성을 위해 플레이스홀더를 함께 제공하는 것이 좋습니다.

예: framer-optim-2.jsx

오버라이드에도 동일한 접근 적용

커스텀 오버라이드의 경우에도 다음과 같은 방식이 필요합니다:

• 플레이스홀더 사용 또는

• 최적화에서 제외

예: framer-optim-3.jsx

추가 도움이 필요하신가요?

문제를 해결하지 못하셨다면 Framer 연락처 페이지를 통해 문의해주시거나, Developer Space를 참고해보세요.

본 글은 Framer 공식 블로그의 'How to fix custom code optimization errors like “Cannot Set Property of Undefined"'를 번역·각색한 콘텐츠입니다.