Getting Started with React Native

Starting for the first time?

If you're new to Apps in Toss development, or if you want to quickly build a mini app with AI, read the Build a mini app with AI guide first.

This is a development approach using the React Native-based Granite framework. It's a good fit for teams that need native-level UI/UX or want to create an experience that blends naturally with the Toss app.

• We want to provide an experience consistent with the native UI of the Toss app.
• We need complex animations or gesture handling.
• We're a team with React Native development experience.

Note

Libraries that require native modules can only be used within the scope supported by Apps in Toss.

If you want to develop with WebView → Getting started with WebView

---

1. Create a project

Run the following command in the location where you want to create the app.

npm

npm create granite-app@"^1"

pnpm

pnpm create granite-app@"^1"

yarn

yarn create granite-app@"^1"

1-1. Set the app name

Enter the app name in kebab-case format.

my-granite-app

1-2. Choose tools

When creating a project, you can choose code quality tools.

• prettier + eslint: Handles code formatting and linting, respectively. It supports flexible code quality management with detailed settings and a variety of plugins.
• biome: A fast, integrated formatting and linting tool based on Rust. It enables efficient work with simple settings.

1-3. Install dependencies

Move to the project folder, then install the dependencies.

npm

cd my-granite-app
npm install

pnpm

cd my-granite-app
pnpm install

yarn

cd my-granite-app
yarn install

[Watch video](../resources/tutorials/react-native/react-native-tutorial-scaffold.mp4)

---

2. Install the framework

To use the Apps in Toss SDK, @apps-in-toss/framework you need to install the package.

npm

npm install @apps-in-toss/framework

pnpm

pnpm add @apps-in-toss/framework

yarn

yarn add @apps-in-toss/framework

---

3. Edit the configuration file

ait init You can use the command to set up the basic environment needed for app development.

npm

npx ait init

pnpm

pnpm ait init

yarn

yarn ait init

1. Select a framework.
2. App name (appName) should be entered. Please enter the same name that was registered in the Apps in Toss console.

When initialization is complete, granite.config.ts a file will be created in the project root. appName, displayName, iconPlease update them to match the app information registered in the Apps in Toss console.

import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';

export default defineConfig({
  appName: '<app-name>', // Change this to the app name registered in the Apps in Toss console.
  plugins: [
    appsInToss({
      brand: {
        displayName: 'App name', // Change this to the app's Korean name displayed on screen.
        primaryColor: '#3182F6', // Change this to the app's primary color displayed on screen.
        icon: null, // Enter the URL of the image uploaded in the console. (In the console's app information, right-click the uploaded image and copy the link, then paste it here.)
      },
      permissions: [],
    }),
  ],
});

---

4. Install TDS

TDS(Toss Design System) React Native Using the package makes it easy to apply components based on the Toss Design System.

npm

npm install @toss/tds-react-native

yarn

yarn add @toss/tds-react-native

pnpm

pnpm add @toss/tds-react-native

For how to use TDS components and guides, TDS React Native documentationplease check it.

You can't test TDS locally

TDS doesn't work in a local browser. Sandbox appPlease test through it.

---

5. Run the development server

npm

npm run dev

pnpm

pnpm dev

yarn

yarn dev

Once the Metro development server is running, you can view the mini app in the Sandbox app. For detailed instructions on testing in the Sandbox app, Sandbox app please check the documentation.

If a too many open files error occurs

Delete the node_modules directory and then reinstall the dependencies.

rm -rf node_modules
npm install  # or use the one that matches yarn or pnpm

---

6. Run the mini app

Run on an iOS simulator

1. Run the Sandbox app.
2. Enter the scheme and press the "Open Scheme" button. Example: intoss://kingtoss
3. At the top of the screen, Bundling {n}%...If it appears, the connection was successful.

[Watch video](../resources/development/local-server/rn-local-develop-ios-sim-example.mp4)

Run on a physical iOS device

To run on an iPhone, it must be connected to the same Wi-Fi as the local server.

1. When you run the Sandbox app, "Local Network" a permission request message appears. "Allow" please press the button.
2. On the server address input screen, enter the local server IP address and save it.

   • On macOS, ipconfig getifaddr en0 you can check the IP address with this command.
3. Press the "Open Scheme" button.
4. At the top of the screen, Bundling {n}%...If it appears, the connection was successful.

Watch video

How to manually allow the "Local Network" permission

1. In the iPhone [Settings] app, "Apps in Toss" search for it and go to it.
2. "Local Network" Turn on the option.

Run on an Android physical device or emulator

1. Connect the Android physical device to your computer with a USB cable.
2. adb connect the port with the command.

   adb reverse tcp:8081 tcp:8081
   adb reverse tcp:5173 tcp:5173

   To connect a specific device, -s add the option.

   adb -s {device-id} reverse tcp:8081 tcp:8081
   adb -s {device-id} reverse tcp:5173 tcp:5173

3. In the Sandbox app, enter the scheme and press the Run button. Example: intoss://kingtoss
4. When the bundling progress status appears at the top of the screen, the connection is complete.

[Watch video](../resources/development/local-server/rn-local-develop-android-example.mp4)

Commonly used adb commands

# Disconnect
adb kill-server

# Connect ports
adb reverse tcp:8081 tcp:8081
adb reverse tcp:5173 tcp:5173

# Check connection status
adb reverse --list

---

7. Debugging

Preparation

React Native Debugger requires the Chrome browser. If it's not installed, Chrome web browserplease download it first.

Debugging with the Metro development server

With the development server running, j pressing the key in the terminal opens React Native Debugger. It only opens when the device and Metro server are connected.

The debugger provides the tabs below.

• Console: console.log You can view logs recorded with these, and run code directly in the REPL environment.
• Source: You can view running code and add breakpoints.
• Network: You can view network requests and responses.
• Memory: You can profile Hermes engine memory usage.
• Profiler: You can measure code execution performance.

Debugging with Breakpoints

To set a breakpoint, Cmd + Popen the file search window and select a file. Click the line you want to add a breakpoint to, and it will be added. When the code reaches that point, execution stops and you can check the current state.

In the source code, debugger if you add the keyword, the code will automatically stop at that point.

Debugging exception cases

Source tab you can enable the options below in the Breakpoints section at the top right.

• Pause on uncaught exceptions: Automatically pauses code when an unexpected exception occurs.
• Pause on caught exceptions: Pauses on all exceptions, regardless of whether they are handled.

Please note

There's a bug where exception breakpoints don't work properly after the service has completely stopped. You can fix it by restarting the development server and React Native Debugger.

Debugging with React DevTools

With React DevTools, you can visually explore component structure and debug it.

If the service is running, refresh the RN view in development mode with the R key. When a screen like the one below appears, the connection is complete.

If you're using an Android device,

adb reverse tcp:8097 tcp:8097 you need to open the port with the command so React DevTools works properly.

Inspecting elements

After pressing the element selection button and touching the element you want to inspect on the device, React DevTools will jump directly to that element.

[Watch video](../resources/learn-more/debugging/inspecting.mp4)

Changing props

You can check the selected component's props and change them in real time. Double-click the prop you want, enter a value, and it will be applied immediately.

[Watch video](../resources/learn-more/debugging/changing-prop.mp4)

Troubleshooting

The Metro development server is open, but the `Something went wrong for a moment` message is displayed

You may not be properly connected to the development server. Disconnect the `adb` connection and reconnect ports 8081 and 5173.

It says there are no connectable devices

The development server and device connect when the React Native View appears. If there are no connectable devices, check whether the development server is building properly.

REPL doesn't work

Due to a React Native bug, REPL may stop responding. Click the eye-shaped icon next to the Console tab, then enter arbitrary code such as `__DEV__`, `1`, etc. in the input field and evaluate it.

The network inspector doesn't work

The network inspector does not support multiple instances. If the socket connection gets tangled, try resolving it in the order below.

1. Close the app completely.
2. Stop the development server and close the network inspector.
3. Restart the app and dev run the script.

If this still doesn't solve it, please report it to the person in charge.

---

8. Build

A bundle file is .ait a file with the .ait extension, the packaged result of the built project.

npm

npm run build

pnpm

pnpm build

yarn

yarn build

When the build is complete, <service-name>.ait a file will be created in the project root. For detailed testing instructions, Toss app please refer to the documentation.

---

9. Release

For how to release, mini app release please refer to the documentation.