[Framer-motion] motion/react vs motion/react-client 비교

Next.js App Router에서 Motion을 사용하다 보면 다음 두 가지 방식이 있다.

// 일반적인 방식
"use client";

import { motion } from "motion/react";

// React Server Components 환경
import * as motion from "motion/react-client";

둘의 차이는 단순히 import 경로가 아니라 컴포넌트가 어느 렌더링 경계에 배치되는지, 서버와 클라이언트에서 어떤 작업이 수행되는지, 브라우저로 전달되는 JavaScript의 범위가 어떻게 달라지는지에 있다.

---

1. motion/react

motion/react를 사용하려면 Motion을 사용하는 컴포넌트에 "use client"를 선언해야 한다.

"use client";

import { motion } from "motion/react";

export default function Page() {
  return (
    <motion.div
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
    >
      Hello
    </motion.div>
  );
}

렌더링 흐름을 단순화하면 다음과 같다.

Browser
   │
   │ Request
   ▼
Next.js Server
   │
   ├─ Page (Client Component)
   ├─ Client Component 렌더링
   ├─ HTML 생성
   └─ RSC Payload
   │
   ▼
Browser
   │
   ├─ HTML 표시
   ├─ Client JS 다운로드
   │
   ▼
Hydration
   │
   ├─ React 이벤트 및 상태 연결
   ├─ Motion 로직 초기화
   └─ Motion 컴포넌트 활성화
   │
   ▼
Animation 실행

렌더링 흐름에서 달라지는 주요 내용

1. 컴포넌트의 렌더링 경계가 클라이언트로 이동한다

"use client"는 해당 파일을 Client Component의 시작점으로 만든다.

따라서 해당 파일은 서버에서만 실행되는 컴포넌트가 아니라, 브라우저에서 실행할 JavaScript를 포함하는 클라이언트 렌더링 경계가 된다.

"use client"
     │
     ▼
해당 파일이 Client Boundary가 됨
     │
     ▼
컴포넌트 코드가 클라이언트 번들에 포함됨

2. 컴포넌트 코드가 클라이언트 번들에 포함된다

서버에서 HTML을 생성하더라도, 해당 Client Component를 브라우저에서 동작시키려면 관련 JavaScript가 클라이언트로 전달되어야 한다.

Server
  │
  ├─ HTML 생성
  └─ Client JS 번들 생성
          │
          ▼
       Browser
          │
       Hydration

즉 초기 HTML은 서버에서 생성될 수 있지만, Motion 컴포넌트를 활성화하기 위한 JavaScript 다운로드와 Hydration이 필요하다.

3. 서버 전용 로직을 같은 컴포넌트에서 직접 사용할 수 없다

Client Component가 된 파일에서는 서버 전용 API나 서버에서만 실행되어야 하는 로직을 직접 사용할 수 없다.

예를 들어 다음과 같은 작업은 별도의 Server Component에서 처리한 뒤 props나 children으로 전달해야 한다.

- 데이터베이스 접근
- 서버 전용 모듈 사용
- 서버 전용 환경 변수 접근
- 서버에서만 실행되어야 하는 데이터 조회

따라서 페이지 전체가 Client Component가 될 필요가 없다면 Client Boundary를 가능한 아래쪽으로 내리는 것이 유리하다.

---

2. motion/react-client

Motion은 Next.js의 RSC 환경을 위해 별도의 entry point를 제공한다.

import * as motion from "motion/react-client";

export default async function Page() {
  const data = await getData();

  return (
    <motion.div
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
    >
      {data.title}
    </motion.div>
  );
}

이 경우 Page 자체에 "use client"를 선언하지 않아도 된다.

렌더링 흐름은 다음과 같이 이해할 수 있다.

Browser
   │
   │ Request
   ▼
Next.js Server
   │
   ├─ Page (Server Component)
   │    │
   │    ├─ getData()
   │    └─ Server rendering
   │
   └─ motion.div
         │
         ▼
      Client Boundary
   │
   ├─ HTML
   └─ RSC Payload
   │
   ▼
Browser
   │
   ├─ HTML 표시
   ├─ Motion Client JS 다운로드
   │
   ▼
Motion 부분 Hydration
   │
   ▼
Animation 실행

렌더링 흐름에서 달라지는 주요 내용

1. 페이지의 기본 렌더링 경계가 서버에 유지된다

Page에 "use client"가 없으므로 페이지는 계속 Server Component로 동작한다.

Page
 │
 ├─ 서버에서 실행
 ├─ 서버에서 데이터 조회
 ├─ 서버에서 HTML 및 RSC Payload 생성
 └─ Motion 부분만 클라이언트 기능 사용

즉 Motion을 사용하더라도 페이지 전체가 Client Component로 전환되지 않는다.

2. Client Boundary가 Motion 컴포넌트 내부에 한정된다

motion/react-client는 Motion이 제공하는 컴포넌트 자체를 Client Component로 연결한다.

Page (Server Component)
       │
       ▼
motion.div (Client Component)
       │
       ▼
Motion Hydration

이 구조에서는 페이지와 데이터 조회 로직은 서버에 남고, Motion 애니메이션에 필요한 부분만 클라이언트에서 활성화된다.

3. 서버 데이터 조회가 서버에서 계속 수행된다

다음과 같은 코드는 Client Component로 전환되지 않고 서버에서 실행된다.

export default async function Page() {
  const data = await getData();

  return (
    <motion.div>
      {data.title}
    </motion.div>
  );
}

렌더링 흐름은 다음과 같다.

Next.js Server
     │
     ├─ Page 실행
     ├─ getData() 실행
     ├─ 서버 전용 로직 수행
     ├─ HTML 생성
     └─ RSC Payload 생성
              │
              ▼
           Browser
              │
        motion.div hydrate
              │
              ▼
        Motion animation

4. 클라이언트로 전달되는 JavaScript의 범위를 줄일 수 있다

페이지 전체가 Client Component가 되는 대신 Motion 컴포넌트에 필요한 클라이언트 코드만 연결된다.

Server Component 코드
        │
        └─ 브라우저에서 다시 실행할 필요 없음

Motion Client Component
        │
        └─ 브라우저에서 Hydration 필요

따라서 초기 HTML 생성과 데이터 조회는 서버에서 처리하고, 애니메이션 실행에 필요한 JavaScript만 클라이언트에서 사용할 수 있다.

---

3. Server Component를 motion.div 내부에 넣는다면?

여기서 RSC의 Composition Model이 중요하다.

import * as motion from "motion/react-client";

export default async function Page() {
  return (
    <motion.div>
      <Profile />
    </motion.div>
  );
}

Profile이 Server Component라면 구조는 다음과 같다.

Page
│
├─ Server Component
│
└─ motion.div
     │
     └─ Profile
          └─ Server Component

motion.div가 Client Component라고 해서 Profile까지 Client Component가 되는 것은 아니다.

렌더링 흐름에서 달라지는 주요 내용

1. Client Component와 Server Component가 하나의 트리 안에 공존한다

Page (Server Component)
│
└─ motion.div (Client Component)
     │
     └─ Profile (Server Component)

Client Boundary가 존재하더라도 그 아래의 모든 컴포넌트가 자동으로 Client Component가 되는 것은 아니다.

2. Server Component의 결과는 서버에서 먼저 생성된다

Profile은 서버에서 실행되고, 그 결과는 RSC Payload에 포함되어 클라이언트로 전달된다.

Next.js Server
     │
     ├─ Page 실행
     ├─ Profile 실행
     ├─ DB / API 접근
     ├─ 서버에서 결과 생성
     └─ RSC Payload 생성
              │
              ▼
           Browser
              │
        motion.div hydrate
              │
              ▼
        Motion animation

3. children은 서버에서 생성된 결과로 전달된다

motion.div는 클라이언트에서 동작하지만, 내부의 Profile은 서버에서 렌더링된 결과로 전달될 수 있다.

Server
  │
  ├─ Profile 렌더링
  └─ motion.div에 전달할 children 생성
          │
          ▼
       Browser
          │
  motion.div 클라이언트 동작 활성화

따라서 motion/react-client를 사용하면 서버에서 수행할 수 있는 작업은 계속 서버에서 수행하면서, Motion에 필요한 클라이언트 동작만 클라이언트에서 실행하는 구조를 만들 수 있다.

---

4. 실제 Motion 소스 코드 확인

이 동작이 어떻게 구성되어 있는지 Motion의 소스 코드를 따라가 보면 더 명확하다.

현재 Motion 패키지의 motion/react-client entry는 다음 파일에서 시작한다.

packages/motion/src/react-client.ts

이 파일은 framer-motion/client를 다시 export하는 매우 얇은 entry point다.

motion/react-client
       │
       ▼
packages/motion/src/react-client.ts
       │
       ▼
framer-motion/client
       │
       ▼
Motion Client Components

그리고 실제 Motion HTML element를 만드는 부분은 다음 위치에서 확인할 수 있다.

packages/framer-motion/src/render/components/motion/elements.ts

여기에는 "use client"가 선언되어 있고, MotionDiv 역시 createMotionComponent("div") 형태로 생성된다.

elements.ts
       │
       ├─ "use client"
       │
       └─ MotionDiv
             │
             ▼
       createMotionComponent("div")

렌더링 흐름에서 달라지는 주요 내용

motion/react-client는 페이지에 "use client"를 추가하는 방식이 아니라, Motion 내부의 컴포넌트 구현에 Client Boundary를 포함하는 방식으로 동작한다.

motion/react-client
        │
        ▼
Motion 내부 Client Entry
        │
        ▼
MotionDiv 자체가 Client Component
        │
        ▼
페이지는 Server Component로 유지

그리고 이 createMotionComponent를 실제로 구성하는 핵심 코드가 다음 파일이다.

packages/framer-motion/src/render/components/motion/create.ts

create.ts 소스 보기

이 파일에서는 createMotionComponentWithFeatures()가 Motion Component를 생성하면서 feature bundle과 DOM visual element를 연결한다.

결국 우리가 작성하는:

<motion.div animate={{ opacity: 1 }} />

는 개념적으로 다음 구조를 거친다.

motion/react-client
        │
        ▼
framer-motion/client
        │
        ▼
MotionDiv
        │
        ▼
createMotionComponent("div")
        │
        ▼
createMotionComponentWithFeatures()
        │
        ├─ Motion features
        └─ DOM Visual Element

이 구조의 핵심은 Motion 컴포넌트 자체는 클라이언트에서 동작하지만, Motion 컴포넌트를 사용하는 상위 페이지까지 클라이언트로 전환하지 않는다는 점이다.

---

결론

Next.js App Router에서 두 방식의 차이를 렌더링 흐름 관점으로 정리하면 다음과 같다.

motion/react

"use client"
     │
     ▼
사용자 컴포넌트가 Client Boundary
     │
     ├─ 컴포넌트 코드가 클라이언트 번들에 포함
     ├─ 클라이언트에서 Hydration 필요
     ├─ 서버 전용 로직을 같은 파일에서 직접 사용하기 어려움
     └─ Motion 활성화
     │
     ▼
Animation 실행


motion/react-client

Server Component
     │
     ├─ 서버에서 렌더링
     ├─ 서버에서 데이터 fetching
     ├─ 서버 전용 로직 수행
     └─ Server Components 유지
     │
     ▼
motion.div
     │
     ├─ Motion 내부에 Client Boundary 존재
     ├─ Motion 관련 코드만 클라이언트에서 활성화
     └─ Motion 부분만 Hydration
     │
     ▼
Animation 실행

두 방식의 렌더링 흐름에서 가장 중요한 차이는 다음과 같다.

구분	motion/react	motion/react-client
Client Boundary	사용하는 파일에 직접 생성	Motion 컴포넌트 내부에 존재
페이지 컴포넌트	Client Component가 됨	Server Component로 유지 가능
데이터 조회	별도 Server Component로 분리 필요	같은 페이지에서 서버 데이터 조회 가능
서버 전용 로직	같은 파일에서 직접 사용하기 어려움	서버에서 계속 실행 가능
클라이언트 JavaScript	해당 Client Component 범위에 포함	Motion에 필요한 범위로 한정
Hydration	Client Component 전체에 필요	Motion 컴포넌트 중심으로 수행
Server Component 조합	별도 구성 필요	Motion 내부에 Server Component를 children으로 전달 가능

 

따라서 단순히 Motion을 사용하기 위해 페이지 전체를 Client Component로 만들 필요가 없다면 **motion/react-client**가 Next.js의 RSC 모델에 더 자연스럽게 맞는 선택이라고 볼 수 있다.

반면 useMotionValue, useScroll, useState, useEffect 등 React의 클라이언트 기능을 직접 사용하는 컴포넌트라면 해당 컴포넌트를 명시적으로 Client Component로 만들고 motion/react를 사용하는 방식이 적합하다.