SDK 2.0.1 마이그레이션
SDK 2.0.1은 React Native 0.84 및 React 19 대응을 포함하는 메이저 업데이트예요.
토스앱의 React Native 업데이트가 예정되어 있어 SDK 1.x를 사용하는 경우 향후 정상 동작을 보장할 수 없어요.
앱인토스 파트너사는 SDK 2.0.1 으로 반드시 마이그레이션해 주세요.
주의하세요
2026년 3월 23일 이후에는 SDK 1.x로 빌드한 앱 번들을 콘솔에 업로드할 수 없어요.
1.x 기반 프로젝트는 신규 배포 및 업데이트가 제한돼요.
기한 내 업데이트가 되지 않을 경우, 별도 연락 및 서비스 운영이 중단될 수 있어요.
왜 마이그레이션이 필요한가요?
- React Native 0.72는 보안 패치와 유지보수가 종료되었어요.
- 2026년 3월 30일 토스앱이 RN 0.84 기반으로 업데이트돼요.
- 런타임 및 브리지 레벨에서 하위 버전과의 호환이 보장되지 않아요.
- 안정성과 보안을 위해 최신 버전 사용이 필요해요.
적용 대상
다음에 해당하면 마이그레이션이 필요해요:
@apps-in-toss/framework1.x 사용 프로젝트@apps-in-toss/web-framework1.x 사용 프로젝트granite build커맨드를 사용 중인 프로젝트
변경 사항 요약
1. 빌드 커맨드가 변경돼요
| 기존 | 변경 |
|---|---|
granite build | ait build |
2. React / React Native 버전이 업데이트돼요
| 항목 | 변경 전 | 변경 후 |
|---|---|---|
| React | 18.x | 19.2.3 |
| React Native | 0.72.x | 0.84.0 |
| Types | 18.x | 19.2.3 |
3. 의존성 구조가 변경돼요
SDK 2.0.1에서는 React 및 React Native 버전이 업데이트되고, Granite 기반 패키지 구조가 새롭게 적용돼요.
자동 마이그레이션 명령어를 실행하면 아래 변경 사항이 함께 반영돼요.
주요 패키지 변경 내역
| 패키지 | 변경 전 | 변경 후 |
|---|---|---|
| react | 18.x | 19.2.3 |
| react-dom | 18.x | 19.2.3 |
| react-native | 0.72.x | 0.84.0 |
| @types/react | 18.x | 19.2.3 |
| @types/react-dom | 18.x | 19.2.3 |
| react-test-renderer | 18.x | 19.2.3 |
Granite 관련 패키지
| 패키지 | 변경 전 | 변경 후 |
|---|---|---|
| @granite-js/react-native | - | 1.0.4 |
| @granite-js/native | - | 1.0.4 |
| @granite-js/plugin-core | - | 1.0.4 |
| @granite-js/plugin-env | - | 1.0.4 |
| @granite-js/plugin-hermes | - | 1.0.4 |
| @granite-js/plugin-router | - | 1.0.4 |
| @granite-js/plugin-micro-frontend | - | 1.0.4 |
| @granite-js/plugin-sentry | - | 1.0.4 |
| babel-preset-granite | - | 1.0.3 |
| @toss/tds-react-native | - | 2.0.1 |
| brick-module | - | 0.5.0 |
WebView 마이그레이션
1. 프레임워크를 2.0.1으로 업데이트해 주세요
@apps-in-toss/web-framework의 버전을 2.0.1으로 업데이트해 주세요.
# yarn
yarn add @apps-in-toss/web-framework@2.0.1
# pnpm
pnpm add @apps-in-toss/web-framework@2.0.12. 빌드 커맨드를 변경해 주세요
| 기존 | 변경 |
|---|---|
granite build | ait build |
React Native 마이그레이션
1. 프레임워크를 2.0.1으로 업데이트해 주세요
@apps-in-toss/framework의 버전을 2.0.1으로 업데이트해 주세요.
# yarn
yarn add @apps-in-toss/framework@2.0.1
# pnpm
pnpm add @apps-in-toss/framework@2.0.12. 자동 마이그레이션을 실행해 주세요
# yarn
yarn ait migrate react-native-0-84-0
# npx
npx ait migrate react-native-0-84-0
# pnpm
pnpm ait migrate react-native-0-84-0다음 항목이 자동으로 반영돼요:
package.json의존성 버전 업데이트babel.config.js설정 업데이트granite build→ait build변경
3. 타입 오류를 확인해 주세요
React 19 및 React Native 0.84로 업그레이드로 일부 타입 정의가 변경되었어요.
마이그레이션 이후 아래 항목을 꼭 확인해 주세요:
React.FC관련 타입 오류children타입 정의 변경- React 19 신규 API와의 충돌 여부
- Strict Mode 관련 경고
React 19 업그레이드 가이드 문서를 참고해 주세요.
테스트 안내
- RN 0.84 대응을 위해 2026년 3월 6일 업로드된 최신 샌드박스 앱이 배포되었어요.
- 반드시 3월 6일 업로드 버전 이상의 샌드박스 앱으로 테스트해 주세요.
현재 토스앱 환경에서는 RN 0.84 대응 테스트가 불가해요.
반드시 샌드박스 앱에서 테스트해 주세요.
구버전 샌드박스 앱에서는 RN 0.84 환경 검증이 정상적으로 이루어지지 않을 수 있어요.
테스트 전 샌드박스 앱 버전을 꼭 확인해 주세요.
참고하세요
미니앱 런칭 전 내부 검수 단계에서는 RN 0.84가 적용된 토스앱 환경에서 별도 테스트가 진행될 예정이에요.
마이그레이션 체크리스트
- SDK 2.0.1 으로 업데이트했어요
-
ait migrate react-native-0-84-0를 실행했어요 - 타입 오류를 모두 수정했어요
-
ait build로 빌드가 정상 동작해요 - 최신 샌드박스 환경에서 테스트를 완료했어요
자주 묻는 질문
SDK 2.0.1 전환과 관련해 많이 문의 주시는 내용을 정리했어요.
📌 정책 및 전환 일정 관련
Q. SDK 1.x를 계속 사용하면 어떻게 되나요?
토스앱 RN 0.84 업데이트 이후 정상 동작을 보장할 수 없어요.
2026년 3월 23일 이후에는 1.x로 빌드한 번들을 콘솔에 업로드할 수 없어요.
기한을 지키지 않을 경우 별도 연락 및 서비스 운영이 중단될 수 있어요.
Q. 기존에 출시한 앱도 마이그레이션이 필요한가요?
네, 기존에 출시한 앱도 SDK 2.0.1로 업데이트가 필요해요.
3월 23일 이후에는 SDK 1.x 기반으로 신규 배포 및 업데이트가 불가해요.
Q. 3월 23일 이후 기존 사용자들은 어떻게 되나요?
이미 출시된 1.x 기반 미니앱은 기존 버전으로 계속 동작해요.
다만, 신규 업데이트는 불가해요.
Q. 토스앱을 업데이트하지 않은 사용자는 어떻게 되나요?
토스앱을 업데이트하지 않은 사용자는 기존 RN 0.72 기반 환경에서 계속 서비스를 이용하게 돼요.
내부적으로는 5월 말 기준 80~90% 이상의 사용자 전환을 예상하고 있어요.
Q. 토스앱 강제 업데이트 계획이 있나요?
5월 이후에도 업데이트 비율이 낮을 경우 강제 업데이트를 고려하고 있어요.
구체적인 일정은 확정되는 대로 별도 안내드릴 예정이에요.
Q. 미니앱 자체에서 구버전 차단 로직을 넣어도 되나요?
네, 가능합니다.
원격 제어 방식으로 특정 버전 이하를 차단하는 로직을 두는 것도 허용돼요.
Q. RN 0.84로 빠르게 전환한 배경이 궁금해요.
내부적으로 장기간 준비를 진행해왔고,
RN 0.84와 주요 서드파티 라이브러리 호환성 테스트를 내부적으로 완료했어요.
단계적으로 검증을 진행한 뒤 안정성이 확인되어 전환을 결정했어요.
🧪 테스트 및 출시 관련
Q. RN 0.84가 적용된 토스앱은 외부에서 테스트할 수 없나요?
현재 RN 0.84가 적용된 토스앱은 외부 테스트용으로 제공되지 않아요.
파트너사에서는 최신 샌드박스 앱에서 테스트해 주세요.
제출된 번들은 내부 검수 단계에서 RN 0.72 / 0.84 토스앱 환경 모두에서 Android / iOS 테스트를 진행해요.
Q. 검토 요청은 언제 넣으면 되나요?
샌드박스 테스트 및 토스앱 QR 테스트에서 이상이 없다면 바로 검토 요청해 주세요.
검토 요청이 접수되면 내부에서 RN 0.84 토스앱 환경에서도 추가 검증을 진행해요.
Q. RN 0.84가 적용된 토스앱은 언제 사용자에게 배포되나요?
3월 30일부터 점진적으로 배포될 예정이에요.
강제 업데이트가 아니기 때문에 사용자 설정에 따라 업데이트 시점이 달라질 수 있어요.
내부적으로는 5월 말 기준 80~90% 전환을 예상하고 있어요.
Q. WebView도 React 19로 반드시 올려야 하나요?
아니에요.
React Native 미니앱만 React 19로 업데이트가 필수예요.
WebView 미니앱은 React 18.x를 유지해도 괜찮아요.
Q. SDK 1.x 전용 샌드박스 앱은 제공되지 않나요?
별도의 72 전용 샌드박스 앱은 제공하지 않아요.
최신 샌드박스 앱에서 하위 SDK 버전 테스트가 가능해요.
🛠 기술 이슈 및 문제 해결
Q. 자동 마이그레이션 후에도 오류가 발생해요.
React 19 및 RN 0.84 변경으로 인해 일부 수동 수정이 필요할 수 있어요.
빌드 로그를 확인해 타입 및 의존성 충돌을 해결해 주세요.
Q. SDK 2.0.1 마이그레이션 후 StackOverflowError가 발생해요.
메트로 서버 연결 문제로 발생하는 경우가 많아요.adb reverse tcp:8081 tcp:8081 명령어가 정상 작동하는지 확인해 주세요.
Q. iOS 샌드박스에서 8081 포트 접속 시 오류가 발생해요.
현재 일부 환경에서 8081 포트 접속 시 오류가 발생하고 있어 수정 중이에요.
우선 IP 기반 접속으로 테스트해 주세요.
Q. 최신 샌드박스 앱 로그인이 되지 않아요.
아래 두 가지를 확인해 주세요:
- 콘솔 로그인 계정 및 비밀번호 만료 여부 확인
- 메트로 서버 연결 상태 확인
문의
마이그레이션 관련 문의는 채널톡 또는 커뮤니티를 통해 문의해 주세요.