> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/sdk-2.x-migration.md). # SDK 2.x Migration The SDK 2.x update is a major update that includes support for React Native 0.84 and React 19.\ The Toss app’s React Native update is scheduled, so **If you are using SDK 1.x, future proper operation cannot be guaranteed.** Apps in Toss partners **Please 반드시 migrate to SDK 2.x.** The latest 2.x version as of now is `2.10.8` It is. {% hint style="warning" %} After March 23, 2026, you will not be able to upload app bundles built with SDK 1.x to the console.\ Projects based on 1.x will have restrictions on new releases and updates. If you do not update by the deadline, separate contact and service operation may be suspended. {% endhint %} {% hint style="info" %} **Please download the latest SDK version.** The latest SDK generally includes the following changes. * Security and stability improvements * New features and API additions * Existing bug fixes and cleanup of deprecated features {% endhint %} *** ### Why is migration necessary? * React Native 0.72 has reached end of security patches and maintenance. * On March 30, 2026, the Toss app will be updated to be based on RN 0.84. * Compatibility with lower versions is not guaranteed at the runtime and bridge levels. * You need to use the latest version for stability and security. *** ### Applicable targets If the following applies to you, migration is needed: * `@apps-in-toss/framework` Projects using version 1.x * `@apps-in-toss/web-framework` Projects using version 1.x * `granite build` Projects using the command *** ### Summary of changes #### 1. The build command changes | Existing | Changed | | --------------- | ----------- | | `granite build` | `ait build` | #### 2. React / React Native versions are updated | Item | Before change | After change | | ------------ | ------------- | ------------ | | React | 18.x | 19.2.3 | | React Native | 0.72.x | 0.84.0 | | Types | 18.x | 19.2.3 | #### 3. The dependency structure changes In SDK 2.x, the React and React Native versions are updated, and a new Granite-based package structure is applied.\ When you run the automatic migration command, the changes below will be applied as well. **Main package changes** | Package | Before change | After change | | ------------------- | ------------- | ------------ | | 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-related packages** | Package | Before change | After change | | --------------------------------- | ------------- | ------------ | | @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.2 | | brick-module | - | 0.5.0 | *** ### WebView migration #### 1. Please update the framework to 2.x `@apps-in-toss/web-framework`the version of **2.x**Please update it to. ```bash # npm npm install @apps-in-toss/web-framework@2.10.8 # yarn yarn add @apps-in-toss/web-framework@2.10.8 # pnpm pnpm add @apps-in-toss/web-framework@2.10.8 ``` #### 2. Please change the build command | Existing | Changed | | --------------- | ----------- | | `granite build` | `ait build` | *** ### React Native migration #### 1. Please update the framework to version 2.x `@apps-in-toss/framework`the version of **2.x**Please update it to. ```bash # npm npm install @apps-in-toss/framework@2.10.8 # yarn yarn add @apps-in-toss/framework@2.10.8 # pnpm pnpm add @apps-in-toss/framework@2.10.8 ``` #### 2. Please run automatic migration ```bash # npx npx ait migrate react-native-0-84-0 # yarn yarn ait migrate react-native-0-84-0 # pnpm pnpm ait migrate react-native-0-84-0 ``` The following items will be applied automatically: * `package.json` Dependency version updates * `babel.config.js` Configuration updates * `granite build` → `ait build` Changed #### 3. Please check for type errors Some type definitions have changed due to the upgrade to React 19 and React Native 0.84.\ Please make sure to check the items below after migration: Please make sure to check the items below after migration: * `React.FC` Related type errors * `children` Type definition changes * Whether there are conflicts with the new React 19 APIs * Warnings related to Strict Mode [React 19 upgrade guide document](https://react.dev/blog/2024/04/25/react-19-upgrade-guide)Please refer to *** ### Test guide * For RN 0.84 support **The latest sandbox app uploaded on March 6, 2026 has been deployed.** * Be sure to **Please test with a sandbox app version uploaded on March 6 or later.** [Download the latest sandbox app](/landing-page/landing-page-en/development/test/sandbox.md) > In the current Toss app environment, RN 0.84 support testing is not possible.\ > Please make sure to test in the sandbox app. In older sandbox app versions, RN 0.84 environment verification may not work properly.\ Please be sure to check the sandbox app version before testing. *** ### Migration checklist * [ ] Updated to SDK 2.x * [ ] `ait migrate react-native-0-84-0`Ran * [ ] Fixed all type errors * [ ] `ait build`Build works properly with * [ ] Testing has been completed in the latest sandbox environment *** ### Frequently asked questions We have organized the questions we receive most often about the switch to SDK 2.x. #### 📌 Policy and transition schedule related **Q. What happens if I keep using SDK 1.x?** After the Toss app RN 0.84 update, proper operation cannot be guaranteed.\ After March 23, 2026, you will not be able to upload bundles built with 1.x to the console. If you do not meet the deadline, separate contact and service operation may be suspended. **Q. Do existing released apps also need to migrate?** Yes, existing released apps also need to be updated to SDK 2.10.8.\ After March 23, SDK 1.x-based new releases and updates will not be possible. **Q. What happens to existing users after March 23?** Mini-apps already released based on 1.x will continue to work with the existing version.\ However, new updates will not be possible. **Q. What happens to users who have not updated the Toss app?** Users who have not updated the Toss app will continue using the existing RN 0.72-based environment.\ Internally, we expect over 80–90% user migration by the end of May. **Q. Is there a plan to force-update the Toss app?** If the update rate remains low even after May, we are considering a forced update.\ We will provide separate notice once the specific schedule is finalized. **Q. Can we add logic in the mini-app itself to block older versions?** Yes, that is possible.\ It is also allowed to have logic that blocks versions below a certain level via remote control. **Q. I’m curious about the background behind the rapid move to RN 0.84.** Internally, we have been preparing for a long time,\ and we have completed compatibility testing with RN 0.84 and major third-party libraries internally. After gradually verifying step by step, we decided to switch once stability was confirmed. #### 🧪 Testing and release related **Q. Can the Toss app with RN 0.84 be tested externally?** The Toss app with RN 0.84 is not currently provided for external testing.\ Partners, please test in the latest sandbox app. Submitted bundles are tested in Android / iOS in both RN 0.72 / 0.84 Toss app environments during the internal review stage. **Q. When should I submit a review request?** If there are no issues in sandbox testing and Toss app QR testing, please submit a review request right away.\ Once the review request is received, we will perform additional verification internally in the RN 0.84 Toss app environment as well. **Q. When will the Toss app with RN 0.84 be distributed to users?** It will be rolled out gradually starting March 30.\ Since this is not a forced update, the update timing may vary depending on user settings. Internally, we expect an 80–90% migration rate by the end of May. **Q. Does WebView also have to be upgraded to React 19?** No.\ Only React Native mini-apps are required to be updated to React 19.\ WebView mini-apps can keep React 18.x. **Q. Is there no sandbox app dedicated to SDK 1.x?** We do not provide a separate sandbox app dedicated to SDK 1.x (0.72).\ In the latest sandbox app, testing mini-apps based on SDK 1.x is not supported. Please be sure to update to SDK 2.x and then test in the latest sandbox app. #### 🛠 Technical issues and troubleshooting **Q. Errors still occur after automatic migration.** Due to changes in React 19 and RN 0.84, some manual fixes may be necessary.\ Please check the build logs and resolve type and dependency conflicts. **Q. I get a StackOverflowError after migrating to SDK 2.10.8.** This is often caused by a Metro server connection issue.\ `adb reverse tcp:8081 tcp:8081` Please check whether the command works properly. **Q. An error occurs when connecting to port 8081 in iOS sandbox.** We are currently fixing an issue where errors occur when connecting to port 8081 in some environments.\ For now, please test using IP-based access. **Q. I can't log in to the latest sandbox app.** Please check the following two things: 1. Check whether the console login account and password have expired\ If there is no issue with the console account, please contact Channel Talk. 2. Check the Metro server connection status *** ### Inquiry For migration-related inquiries, please contact us via Channel Talk or the community. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/sdk-2.x-migration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.