motiondivision/motion 딥다이브
— 브라우저 네이티브 엔진과 JS 엔진을 섞어 쓰는 하이브리드 애니메이션 라이브러리

1한 줄 정체 — Motion이 뭐 하는 물건인가

Motion은 "무엇을 어떻게 움직일지"를 선언하면, 실제 실행은 라이브러리가 알아서 최적의 방식으로 처리해주는 애니메이션 라이브러리다. 개발자는 animate(".box", { x: 100 })나 <motion.div animate={{ x: 100 }} />처럼 "결과 상태"만 적으면 되고, 그 값을 60fps(또는 120fps)로 부드럽게 그려내는 계산·프레임 스케줄링·하드웨어 가속 여부 판단은 전부 라이브러리 내부에서 처리된다.

React 생태계에서는 <motion.div> 같은 컴포넌트로 가장 널리 알려져 있지만, 실제로는 React 없이도 동작하는 순수 JS 애니메이션 엔진(motion-dom) 위에 React 전용 레이어(framer-motion)가 얹힌 구조다. 그래서 바닐라 JS 페이지, Next.js 서버 컴포넌트, Vue(별도 패키지 motion-v) 등 여러 환경에서 같은 엔진을 재사용한다.

2왜 지금 뜨는가

① "Framer Motion → Motion" 리브랜딩이 자리를 잡았다

2025년 1월 20일 배포된 v12.0.0부터 프로젝트명이 Framer Motion에서 Motion으로 바뀌었다. npm 패키지도 motion으로 새로 나왔고, 기존 framer-motion 패키지는 폐기되지 않고 내부 엔진으로 계속 유지된다. "React 전용 애니메이션 도구"에서 "JS·React·Vue를 아우르는 애니메이션 플랫폼"으로 정체성을 확장한 결과, 검색 트렌드와 채택률이 다시 올라가는 시기다.

② "가볍다 vs 표현력 있다"를 둘 다 만족시키는 하이브리드 엔진

전통적으로 애니메이션 라이브러리는 CSS/WAAPI(가볍고 빠르지만 제약 많음) 아니면 순수 JS(자유롭지만 무겁고 메인 스레드를 먹음) 중 하나를 택해야 했다. Motion은 값 하나하나에 대해 "이 값·이 상황에서 WAAPI로 가속할 수 있는가"를 런타임에 판단해 자동으로 전환한다. 개발자 입장에서는 API가 하나뿐인데 성능은 최적에 가깝다.

③ 레이아웃 애니메이션(FLIP)이라는 어려운 문제를 표준 API로 제공

layout prop 하나로 리스트 재정렬·그리드 변경 같은 레이아웃 변화까지 부드럽게 보간해주는 projection 시스템은 직접 구현하기 매우 어려운 기능이다. 이걸 선언적으로 제공한다는 점이 React 개발자들 사이에서 꾸준히 채택되는 핵심 이유다.

3무엇을 해결하나

Motion이 없다면 개발자는 애니메이션 하나를 만들 때마다 세 가지를 손수 결정해야 한다. ① 어떤 실행 방식(CSS/WAAPI vs JS)을 쓸지, ② 중간에 값이 바뀌면(인터럽트) 어떻게 자연스럽게 이어 붙일지, ③ 리스트 순서·크기가 바뀔 때 요소들의 위치 변화를 어떻게 보간할지. 이 세 가지는 각각 별도의 난이도 높은 문제다.

4전체 구조 — 4개 패키지의 관계

이 저장소는 Yarn 워크스페이스 + Turborepo + Lerna로 관리되는 모노레포다(packages/*). 핵심은 계층이 명확히 분리돼 있고, 아래로 갈수록(React에서 멀어질수록) 의존성이 적어진다는 점이다.

즉 npm install motion으로 설치해 쓰는 코드 대부분은 실제로는 framer-motion 패키지 안의 코드를 실행하는 것이다. motion 패키지는 motion/react·motion/mini처럼 더 명확한 하위 경로(subpath)를 제공하는 얇은 래퍼일 뿐이다. 이 저장소 밖에는 Vue용 motion-v 패키지도 있는데, 그건 별도 저장소로 관리되며 이 모노레포에는 포함돼 있지 않다.

import * as fm from "framer-motion"

export const motion: typeof fm.motion = fm.motion
export const m: typeof fm.m = fm.m

export * from "framer-motion"

5핵심 설계·동작 원리

① 하이브리드 엔진 — "이 값은 WAAPI로 가속해도 되는가?"를 매번 판단

Motion의 핵심은 motion-dom/src/animation/waapi/supports/waapi.ts의 supportsBrowserAnimation() 함수다. 애니메이션을 시작하기 직전마다 아래 조건을 모두 검사해서, 하나라도 걸리면 JS 애니메이션으로 자동 전환한다.

// motion-dom/src/animation/waapi/supports/waapi.ts (요약)
const acceleratedValues = new Set([
  "opacity", "clipPath", "filter", "transform", "backgroundColor"
])

function supportsBrowserAnimation(options) {
  const subject = options.motionValue?.owner?.current
  // ① HTML/SVG 엘리먼트가 아니면(다른 창·팝업 등) 가속 안 함
  if (!(subject instanceof HTMLElement) &&
      !(subject instanceof SVGElement)) return false

  return supportsWaapi() &&
    // ② 가속 가능한 값 목록에 있거나, oklch 등 브라우저 전용 색상 포맷
    (acceleratedValues.has(name) || isBrowserOnlyColor) &&
    // ③ transform인데 커스텀 템플릿이 있으면 WAAPI 불가
    (name !== "transform" || !transformTemplate) &&
    // ④ onUpdate로 매 프레임 값을 읽어야 하면 WAAPI 불가(읽을 방법이 없음)
    !onUpdate &&
    !repeatDelay &&
    repeatType !== "mirror" &&
    damping !== 0 &&
    type !== "inertia"
}

즉 gpu 가속 대상은 opacity·clipPath·filter·transform·backgroundColor 5종 뿐이고, 그마저도 조건이 하나라도 안 맞으면(예: onUpdate를 넘겼다면) 자동으로 JS 경로로 내려간다. WAAPI 경로는 NativeAnimation, JS 경로는 JSAnimation이라는 각각의 클래스가 맡되, 개발자가 부르는 animate() API는 완전히 동일하다.

② animate()·scroll()·inView() — React 없이도 쓰는 독립 함수

packages/framer-motion/src/dom.ts(motion/react가 아닌 motion 기본 진입점이 참조하는 파일)는 다음처럼 세 함수를 노출한다.

// packages/framer-motion/src/dom.ts
export * from "motion-dom"
export * from "motion-utils"
export { animate, createScopedAnimate } from "./animation/animate"
export { scroll } from "./render/dom/scroll"
export { inView } from "./render/dom/viewport"

• animate(selector, keyframes, options) — CSS 셀렉터나 DOM 엘리먼트를 직접 애니메이션. React가 필요 없다.
• scroll(callback, options) — 스크롤 진행률(0~1)을 콜백으로 흘려주는 스크롤 연동 애니메이션. 브라우저가 지원하면 ScrollTimeline(네이티브 스크롤 타임라인)까지 활용한다.
• inView(selector, callback) — IntersectionObserver를 감싼 뷰포트 진입 감지 함수.

이 세 함수는 React 컴포넌트 트리와 무관하게 동작하기 때문에, jQuery 스타일의 바닐라 JS 페이지나 서버 렌더링 위주 사이트에서도 애니메이션 로직만 가볍게 가져다 쓸 수 있다.

③ React 레이어 — motion.div · AnimatePresence · MotionValue

React를 쓸 때는 <motion.div animate={{ x: 100 }} />처럼 태그 이름 앞에 motion.을 붙인다. 내부적으로 motion은 Proxy 객체라서 motion.div·motion.span·motion.custom 등 모든 HTML 태그에 반응한다. 언마운트되는 컴포넌트를 즉시 없애지 않고 exit 애니메이션이 끝날 때까지 붙잡아 두는 것이 AnimatePresence의 역할이다.

값 하나하나는 MotionValue 인스턴스로 관리된다(motion-dom/src/value/index.ts). 이 클래스는 단순히 "현재 값"만 들고 있는 게 아니라, 최근 프레임들 사이의 변화량으로 속도(velocity)를 계산해 둔다. 그래서 애니메이션이 중간에 새 목표로 바뀌어도(인터럽트) 이전 속도를 이어받아 튀지 않고 자연스럽게 방향을 전환할 수 있다.

④ 스프링 물리 — 물리 상수 아니면 지속시간·통통 튐(bounce) 중 선택

motion-dom/src/animation/generators/spring.ts의 기본값은 다음과 같다.

const springDefaults = {
  stiffness: 100, damping: 10, mass: 1.0, velocity: 0.0, // 물리 기반
  duration: 800, bounce: 0.3, visualDuration: 0.3,       // 지속시간 기반(대안)
}

stiffness(뻣뻣함)·damping(감쇠, 저항)·mass(질량) 세 물리 상수로 스프링을 정의할 수도 있고, 물리를 몰라도 되게 duration + bounce(몇 초 동안, 얼마나 튕길지)로 지정할 수도 있다. 내부적으로 후자를 전자로 역산하는 createGeneratorEasing 유틸이 존재한다 — "정확한 스프링 값은 모르지만 어떤 느낌인지는 안다"는 개발자를 위한 배려다.

⑤ 레이아웃 애니메이션(projection) — FLIP을 시스템으로 만든 것

layout prop을 쓰면 HTMLProjectionNode(motion-dom/src/projection/node)가 리렌더링 전후의 getBoundingClientRect() 위치·크기를 기록해 두고, 그 차이만큼을 transform으로 역산해 "실제로는 순간 이동했지만 시각적으로는 부드럽게 움직인 것처럼" 보이게 만든다. 여러 요소가 중첩돼 있으면(부모가 커지고 자식이 그 안에서 재배치되는 경우 등) 이 계산이 트리 구조로 전파돼야 하는데, projection 시스템이 이 전파를 자동으로 처리한다.

⑥ 번들 크기 최적화 — m 컴포넌트 + LazyMotion

motion(전체 motion.*)을 그대로 쓰면 제스처·드래그·레이아웃 기능이 모두 포함돼 번들이 커진다. 대신 기능이 빠진 가벼운 버전인 m 컴포넌트를 쓰고, 필요한 기능 묶음(domAnimation/domMax)을 LazyMotion으로 동기 또는 비동기 code-split으로 불러올 수 있다.

// 동기 로딩
import { LazyMotion, m, domAnimation } from "motion/react"
function App() {
  return (
    <LazyMotion features={domAnimation}>
      <m.div animate={{ scale: 2 }} />
    </LazyMotion>
  )
}
// 비동기 로딩 — 초기 번들에서 애니메이션 로직을 완전히 뺀다
<LazyMotion features={() => import("./domMax-features")}>

package.json의 bundlesize 검사 기준으로 실제 크기 상한이 명시돼 있다: motion 전체 34.9kB · m 6kB · domAnimation 기능 묶음 17.85kB · domMax(레이아웃·드래그 포함) 29.8kB · 독립 함수 animate()만 19.1kB. 이 수치가 CI에서 자동 검증되므로, 실수로 번들이 커지는 회귀가 배포되기 어렵다.

6기술 스택·의존성

버전의 진실원(source of truth)은 각 패키지의 package.json이다. 저장소 루트 package.json은 "name": "motion-one", "version": "0.0.0"로, 실제 배포 버전과 무관한 워크스페이스 메타데이터일 뿐이니 착각하지 말아야 한다. framer-motion의 peerDependencies는 react ^18.0.0 || ^19.0.0이면서 전부 optional: true다 — React 없이 animate()·scroll()만 쓰는 순수 JS 사용도 정식으로 지원된다는 뜻이다.

개발용 도구 체인

7설치·요구사항

8실제 사용 흐름

import { motion } from "motion/react"

function Card() {
  return (
    <motion.div
      initial={{ opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
      whileHover={{ scale: 1.05 }}
      transition={{ type: "spring", stiffness: 300, damping: 20 }}
    >
      카드 내용
    </motion.div>
  )
}

import { motion, AnimatePresence } from "motion/react"

function Modal({ isOpen }) {
  return (
    <AnimatePresence>
      {isOpen && (
        <motion.div
          initial={{ opacity: 0 }}
          animate={{ opacity: 1 }}
          exit={{ opacity: 0 }}
        />
      )}
    </AnimatePresence>
  )
}

import { animate, scroll } from "motion"

scroll(
  animate("#progress-bar", { scaleX: [0, 1] }),
  { target: document.querySelector("#article") }
)

9함정·오해 방지

10대안 비교

11정리 — 누가 쓰면 좋은가

Motion은 "애니메이션을 잘 만들고 싶은데 브라우저 최적화까지 신경 쓸 여유는 없는" React/JS 개발자에게 가장 적합하다. 특히 다음 상황에서 진가를 발휘한다.

• UI 컴포넌트 라이브러리·디자인 시스템을 만들면서 hover·tap·모달 exit 애니메이션을 일관되게 넣고 싶을 때
• 리스트/그리드 재정렬(칸반 보드, 필터링되는 카드 목록 등)에서 요소가 순간이동하지 않고 부드럽게 이동하길 원할 때
• 번들 크기가 민감한 랜딩 페이지에서도 m + LazyMotion으로 애니메이션 코드를 code-split하고 싶을 때
• React 없이도 같은 애니메이션 엔진(animate()·scroll()·inView())을 순수 JS/서버 렌더링 페이지에 재사용하고 싶을 때

반대로 영화 같은 정교한 타임라인 시퀀스·SVG 모핑을 대규모로 다뤄야 하는 모션 디자인 전문 작업이라면 GSAP 계열이 더 나을 수 있고, hover 몇 개 색만 바꾸는 정도라면 굳이 라이브러리를 추가할 필요 없이 CSS만으로 충분하다. 이 저장소를 학습용으로 읽는다면, motion-dom/src/animation/waapi/supports/waapi.ts(하이브리드 판단 로직)와 motion-dom/src/projection(레이아웃 FLIP)부터 시작하는 것을 추천한다 — 이 둘이 Motion이 다른 라이브러리와 구별되는 핵심 설계다.

12직접 해볼 수 있는 실습 과제

실습은 의존성과 Cypress 실행 환경이 준비된 개인 작업 사본에서 진행한다. 아래 명령은 별도 안내가 없으면 Motion 레포 루트에서 실행하며, study-로 시작하는 파일은 독자가 새로 만들 실습 파일이다.

yarn build
yarn workspace react-env dev

첫 명령은 패키지를 빌드하고, 두 번째 명령은 React 개발 앱을 띄운다. dev/react/src/App.tsx는 tests/ 안에서 이름 붙여 내보낸 App을 ?test=파일명으로 불러온다. 파일을 저장한 뒤 브라우저를 새로고침해 변경을 확인한다.

import { useState } from "react"
import { motion } from "motion/react"

export function App() {
    const [moved, setMoved] = useState(false)

    return (
        <motion.button
            type="button"
            animate={{ x: moved ? 160 : 0 }}
            whileHover={{ scale: 1.05 }}
            transition={{
                type: "spring",
                stiffness: 200,
                damping: 20
            }}
            onClick={() => setMoved(!moved)}
        >
            움직임 전환
        </motion.button>
    )
}

cp dev/react/src/tests/scroll-spring.tsx dev/react/src/tests/study-scroll.tsx

const opacity = useTransform(
    scrollYProgress,
    [0, 1],
    [0.3, 1]
)

cp dev/react/src/tests/animate-presence-pop-list.tsx dev/react/src/tests/study-exit-layout.tsx

import { motion } from "motion/react"

export function App() {
    const fallback = new URLSearchParams(
        window.location.search
    ).has("fallback")

    return (
        <motion.button
            data-testid="probe"
            initial={{ opacity: 1 }}
            animate={{ opacity: 0.2 }}
            transition={{
                type: "tween",
                duration: 10,
                ease: "linear"
            }}
            onUpdate={fallback ? () => {} : undefined}
        >
            실행 경로 관찰
        </motion.button>
    )
}

cy.get('[data-testid="probe"]')
    .wait(500)
    .then(([$element]: any) => {
        const opacity = Number(getComputedStyle($element).opacity)
        const running = $element.getAnimations().filter(
            (animation: Animation) =>
                animation.playState === "running"
        )

        expect(opacity).to.be.greaterThan(0.2)
        expect(opacity).to.be.lessThan(1)
        expect(running.length > 0).to.equal(!fallback)
    })

cd packages/framer-motion
yarn cypress run --config-file cypress.json --spec cypress/integration/study-waapi.ts
yarn cypress run --config-file cypress.react-19.json --spec cypress/integration/study-waapi.ts

13관련 기술 심화 학습 로드맵

매주 읽은 파일을 요약하는 데서 끝내지 말고, 화면·관찰 기록·테스트 중 하나를 남긴다. 아래 경로는 모두 레포 루트 기준이며, 패키지의 역할과 값의 흐름을 먼저 이해한 뒤 세부 구현을 읽는 순서다.

마지막에는 입력 변화 → MotionValue → 실행 경로 선택 → 화면 반영 → 완료와 정리를 자신의 실습 화면에 대입해 설명해 본다. 설명이 끊기는 지점의 파일을 다시 읽으면 다음 학습 범위를 좁힐 수 있다.

14핵심 키워드 사전