> 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/ai-vibe-coding/en/tutorials/react-native.md).

# Getting Started with React Native

{% hint style="info" %}
**If you're just getting started?**

If you're new to App in Toss development or want to quickly build a mini app with AI, read the "Build a mini app with AI" guide first.
{% endhint %}

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

* I want to provide an experience consistent with the Toss app's native UI.
* I need complex animations or gesture handling.
* We are a team with React Native development experience.

{% hint style="info" %}
**Please note**

Libraries that require native modules can only be used within the scope supported by App in Toss.
{% endhint %}

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.

{% tabs %}
{% tab title="npm" %}

```sh
npm create granite-app@"^1"
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm create granite-app@"^1"
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn create granite-app@"^1"
```

{% endtab %}
{% endtabs %}

#### 1-1. Set the app name

The app name should be entered in [kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case) format.

```sh
my-granite-app
```

#### 1-2. Choose tools

You can choose code quality tools when creating the project.

* `prettier` + `eslint`: handles code formatting and linting respectively. It supports flexible code quality management with detailed settings and various plugins.
* `biome`: a fast, integrated formatting and linting tool based on Rust. It enables efficient work with simple configuration.

#### 1-3. Install dependencies

Move to the project folder and install the dependencies.

{% tabs %}
{% tab title="npm" %}

```sh
cd my-granite-app
npm install
```

{% endtab %}

{% tab title="pnpm" %}

```sh
cd my-granite-app
pnpm install
```

{% endtab %}

{% tab title="yarn" %}

```sh
cd my-granite-app
yarn install
```

{% endtab %}
{% endtabs %}

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

***

### 2. Install the framework

To use the App in Toss SDK, `@apps-in-toss/framework` package must be installed.

{% tabs %}
{% tab title="npm" %}

```sh
npm install @apps-in-toss/framework
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm add @apps-in-toss/framework
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn add @apps-in-toss/framework
```

{% endtab %}
{% endtabs %}

***

### 3. Edit the configuration file

`ait init` You can set up the basic environment needed for app development with the command.

{% tabs %}
{% tab title="npm" %}

```sh
npx ait init
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm ait init
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn ait init
```

{% endtab %}
{% endtabs %}

1. Select a framework.
2. Enter the app name (`appName`) . Please enter the same name as registered in the App in Toss console.

When initialization is complete, `granite.config.ts` file will be created in the project root. `appName`, `displayName`, `icon`Please change them to match the app information registered in the App in Toss console.

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

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

***

### 4. Install TDS

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

{% tabs %}
{% tab title="npm" %}

```sh
npm install @toss/tds-react-native
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn add @toss/tds-react-native
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm add @toss/tds-react-native
```

{% endtab %}
{% endtabs %}

For TDS component usage and guides, see [TDS React Native documentation](https://tossmini-docs.toss.im/tds-react-native/)please check.

{% hint style="info" %}
**You can't test TDS locally**

TDS does not work in a local browser. [Sandbox app](https://appsintoss.gitbook.io/appsintoss-docs/landing-page/development/test/sandbox)please test through it.
{% endhint %}

***

### 5. Run the development server

{% tabs %}
{% tab title="npm" %}

```sh
npm run dev
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm dev
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn dev
```

{% endtab %}
{% endtabs %}

When the Metro development server is running, you can check the mini app in the Sandbox app. For detailed instructions on testing in the Sandbox app, [Sandbox app](https://appsintoss.gitbook.io/appsintoss-docs/landing-page/development/test/sandbox) please check the documentation.

{% hint style="info" %}
**If you get a too many open files error,**

delete the node\_modules directory and reinstall the dependencies.

```sh
rm -rf node_modules
npm install  # or adapt for yarn or pnpm
```

{% endhint %}

***

### 6. Run the mini app

#### Run on the iOS simulator

1. Run the Sandbox app.
2. Enter the scheme and press the "Open Schema" 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 will appear. **"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 Schema" button.
4. At the top of the screen, `Bundling {n}%...`If it appears, the connection was successful.

Watch video

<details>

<summary>How to manually allow "Local Network" permission</summary>

1. In the iPhone \[Settings] app, **"App in Toss"** search for it and go there.
2. **"Local Network"** turn on the option.

</details>

#### Run on a physical Android device or emulator

1. Connect your Android device to the computer with USB.
2. `adb` connect the ports with the command.

   ```sh
   adb reverse tcp:8081 tcp:8081
   adb reverse tcp:5173 tcp:5173
   ```

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

   ```sh
   adb -s {deviceId} reverse tcp:8081 tcp:8081
   adb -s {deviceId} reverse tcp:5173 tcp:5173
   ```
3. Enter the scheme in the Sandbox app and press the run button. Example: `intoss://kingtoss`
4. If the bundling progress appears at the top of the screen, the connection is complete.

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

<details>

<summary>Commonly used adb commands</summary>

```sh
# Disconnect
adb kill-server

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

# Check connection status
adb reverse --list
```

</details>

***

### 7. Debugging

#### Preparation

React Native Debugger requires the Chrome browser. If it's not installed, [Chrome web browser](https://www.google.com/intl/ko_kr/chrome/)please download it first.

#### Debugging with the Metro development server

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

The debugger provides the following tabs.

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

**Debugging with Breakpoints**

To set a breakpoint, `Cmd` + `P`open the file search window and select a file. Click the line you want, and a breakpoint will be added. When the code reaches that point, execution stops and you can inspect the current state.

In the source code, `debugger` add the keyword to automatically break at that point.

**Debugging exceptions**

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

* **Pause on uncaught exceptions**: automatically stop code when an unexpected exception occurs.
* **Pause on caught exceptions**: stop on all exceptions regardless of whether they are handled.

{% hint style="info" %}
**Be aware**

There is a bug where exception breakpoints do not work properly after the service has completely stopped. Restarting the development server and React Native Debugger can fix it.
{% endhint %}

#### Debugging with React DevTools

With React DevTools, you can visually inspect and debug the component structure.

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

{% hint style="info" %}
**If you're using an Android device,**

`adb reverse tcp:8097 tcp:8097` you must open the port with the command for React DevTools to work properly.
{% endhint %}

**Inspecting elements**

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

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

**Changing props**

You can inspect the props of the selected component and change them in real time. Double-click the prop you want and enter a value to apply it immediately.

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

#### Troubleshooting

<details>

<summary>The Metro development server is open, but a "Something went wrong for a moment" message appears</summary>

It may be a problem with the development server not connecting properly. Disconnect the \`adb\` connection and try reconnecting ports 8081 and 5173.

</details>

<details>

<summary>It says there are no connectable devices</summary>

The development server and device are connected when the React Native view appears. If there are no connectable devices, check whether the development server is being built correctly.

</details>

<details>

<summary>REPL does not work</summary>

Due to a React Native bug, REPL may freeze. Click the eye icon next to the Console tab, then enter any code such as \`\_\_DEV\_\_\` or \`1\` in the input field and evaluate it.

</details>

<details>

<summary>The network inspector does not work</summary>

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

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

If this procedure does not solve it either, please report it to the person in charge.

</details>

***

### 8. Build

The bundle file is `.ait` a file with the extension, and it is the packaged result of the built project.

{% tabs %}
{% tab title="npm" %}

```sh
npm run build
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm build
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn build
```

{% endtab %}
{% endtabs %}

When the build is complete, `<service-name>.ait` file will be created in the project root. For detailed testing instructions, [Toss app](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/toss) please refer to the documentation.

***

### 9. Launch

For how to launch it, [Mini app launch](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/deploy) please refer to the documentation.


---

# 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/ai-vibe-coding/en/tutorials/react-native.md?ask=<question>&goal=<endgoal>
```

`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.