Remotion Upgrading

Remotion 패키지 업그레이드 방법과 SemVer 규칙, 메이저 버전 마이그레이션 가이드를 정리한다.

---

🚀 가장 쉬운 방법: remotion upgrade CLI

프로젝트 루트에서:

매니저	명령
npm	npx remotion upgrade
pnpm	pnpm exec remotion upgrade
yarn	yarn remotion upgrade
bunx	bunx remotion upgrade

📌 @remotion/cli 패키지가 설치되어 있어야 한다.

---

🛠️ 수동 업그레이드

upgrade CLI가 동작하지 않을 때:

1. package.json의 모든 @remotion/* 패키지와 remotion의 버전을 동일한 값으로 수정
2. 버전 앞의 ^를 제거해 정확히 그 버전으로 고정
3. 패키지 매니저 install 실행:

npm i
# or
pnpm i
# or
yarn
# or
bun i

---

📐 SemVer (의미론적 버전) 규칙

Remotion은 SemVer를 따른다. 첫 번째 숫자가 같으면 코드 변경 없이 업그레이드 가능:

현재	업그레이드 가능	호환성
4.0.0	4.0.1, 4.1.100, 4.99.0	✅ 백워드 호환
4.0.0	5.0.0	❌ 마이그레이션 가이드 필요
4.0.0	3.x	❌ 다운그레이드

⚠️ 예외: experimental로 표시된 API는 메이저 버전 사이에서도 변경될 수 있다.

---

🔄 메이저 버전 마이그레이션

버전	가이드
2.x → 3.x	/docs/3-0-migration
3.x → 4.x	/docs/4-0-migration
4.x → 5.x	/docs/5-0-migration
React 19 대응	/docs/react-19

각 마이그레이션은 breaking changes 항목을 먼저 확인하고 진행한다.

---

📋 변경 이력 확인

전체 변경 내역은 remotion.dev/changelog에서 확인한다.

---

🏢 안정 버전 (Enterprise)

엔터프라이즈 고객은 remotion.pro 포털에서 더 엄격한 안정성 보장을 위한 별도 stable repo에 접근할 수 있다.

---

📚 영역 구분

• CLI 도구 업데이트: npx remotion upgrade 후 재시작
• 문제가 생기면: Remotion 트러블슈팅 & 운영
• 한글 hub: Remotion 시작하기

상위 문서: ← Remotion 시작하기 출처: Remotion 공식 문서 — Upgrading Remotion 한글화 (2026-07-29) 공급사: Remotion AG

변경 이력

날짜	변경
2026-07-29	초판 작성 (공식 Upgrading 가이드 한글화)
2026-07-29	메타데이터 블록을 본문 하단으로 이동