> 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" %}
**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.
{% endhint %}

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.

{% hint style="info" %}
**Note**

Libraries that require native modules can only be used within the scope supported by Apps 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

Enter the app name in [kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case) format.

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

{% 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 Apps in Toss SDK, `@apps-in-toss/framework` you need to install the package.

{% 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 use the command to set up the basic environment needed for app development.

{% 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. 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`, `icon`Please update them to match the app information registered in the Apps 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>', // 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.

{% 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 how to use TDS components and guides, [TDS React Native documentation](https://tossmini-docs.toss.im/tds-react-native/)please check it.

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

TDS doesn't 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 %}

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](https://appsintoss.gitbook.io/appsintoss-docs/landing-page/development/test/sandbox) please check the documentation.

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

Delete the node\_modules directory and then reinstall the dependencies.

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

{% endhint %}

***

### 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

<details>

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

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

</details>

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

   ```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 {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)

<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 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` + `P`open 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.

{% hint style="info" %}
**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.
{% endhint %}

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

{% hint style="info" %}
**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.
{% endhint %}

**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

<details>

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

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

</details>

<details>

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

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.

</details>

<details>

<summary>REPL doesn't work</summary>

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.

</details>

<details>

<summary>The network inspector doesn't work</summary>

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.

</details>

***

### 8. Build

A bundle file is `.ait` a file with the .ait extension, 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` a 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. Release

For how to release, [mini app release](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.