> 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/zh/tutorials/react-native.md).

# 开始使用 React Native

{% hint style="info" %}
**如果是第一次开始？**

如果你刚开始开发 Apps in Toss，或者想和 AI 一起快速制作迷你应用，请先阅读《用 AI 制作迷你应用》文档。
{% endhint %}

这是基于 React Native 的 Granite 框架开发方式。适合需要原生级 UI/UX，或希望打造与 Toss应用自然融合体验的团队。

* 我想提供与 Toss应用原生 UI 一致的体验。
* 需要复杂的动画或手势处理。
* 是有 React Native 开发经验的团队。

{% hint style="info" %}
**请注意**

需要原生模块的库只能在 Apps in Toss 支持的范围内使用。
{% endhint %}

如果想用 WebView 开发 → 开始使用 WebView

***

### 1. 创建项目

请在要创建应用的位置执行以下命令。

{% 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. 设置应用名称

应用名称要 [kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case) 格式输入。

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

#### 1-2. 选择工具

创建项目时可以选择代码质量工具。

* `prettier` + `eslint`：分别负责代码格式化和 linting。通过细致的配置和丰富的插件，支持灵活的代码质量管理。
* `biome`：这是一个基于 Rust 的快速、集成式格式化和 linting 工具。通过简单配置即可高效工作。

#### 1-3. 安装依赖

进入项目文件夹后安装依赖。

{% 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 %}

\[观看视频]\(../resources/tutorials/react-native/react-native-tutorial-scaffold.mp4)

***

### 2. 安装框架

要使用 Apps in Toss SDK， `@apps-in-toss/framework` 需要安装该包。

{% 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. 修改配置文件

`ait init` 使用该命令可以配置应用开发所需的基础环境。

{% 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. 请选择框架。
2. 应用名称(`appName`)请输入。请与在 Apps in Toss 控制台注册的名称保持一致。

初始化完成后，项目根目录会生成 `granite.config.ts` 文件。 `appName`, `displayName`, `icon`请修改为与在 Apps in Toss 控制台注册的应用信息一致。

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

export default defineConfig({
  appName: '<app-name>', // 请改为在 Apps in Toss 控制台注册的应用名称。
  plugins: [
    appsInToss({
      brand: {
        displayName: '应用名称', // 请改为显示在界面上的应用韩文名称。
        primaryColor: '#3182F6', // 请改为显示在界面上的应用主色。
        icon: null, // 请输入在控制台上传的图片 URL。（请在控制台的应用信息中右键上传的图片，复制链接后填入）
      },
      permissions: [],
    }),
  ],
});
```

***

### 4. 安装 TDS

**TDS(Toss Design System) React Native** 使用该包可以轻松应用基于 Toss 设计系统的组件。

{% 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 %}

TDS 组件的使用方法和指南请查看 [TDS React Native 文档](https://tossmini-docs.toss.im/tds-react-native/)。

{% hint style="info" %}
**无法在本地测试 TDS**

TDS 无法在本地浏览器中运行。 [沙盒应用](https://appsintoss.gitbook.io/appsintoss-docs/landing-page/development/test/sandbox)请通过它进行测试。
{% endhint %}

***

### 5. 启动开发服务器

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

```sh
npm run dev
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm dev
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn dev
```

{% endtab %}
{% endtabs %}

Metro 开发服务器启动后，可以在沙盒应用中查看迷你应用。关于在沙盒应用中测试的详细方法，请参考 [沙盒应用](https://appsintoss.gitbook.io/appsintoss-docs/landing-page/development/test/sandbox) 文档。

{% hint style="info" %}
**如果出现 too many open files 错误**

请删除 node\_modules 目录后重新安装依赖。

```sh
rm -rf node_modules
npm install  # 或根据 yarn、pnpm 调整
```

{% endhint %}

***

### 6. 运行迷你应用

#### 在 iOS 模拟器中运行

1. 启动沙盒应用。
2. 输入 scheme 并点击“打开 Schema”按钮。示例： `intoss://kingtoss`
3. 如果屏幕顶部 `Bundling {n}%...`显示时，就表示连接成功了。

\[观看视频]\(../resources/development/local-server/rn-local-develop-ios-sim-example.mp4)

#### 在 iOS 真机上运行

要在 iPhone 上运行，需要连接到与本地服务器相同的 Wi‑Fi。

1. 启动沙盒应用后 **"本地网络"** 会显示权限请求消息。 **"允许"** 请点击按钮。
2. 在服务器地址输入界面输入本地服务器 IP 地址并保存。
   * 在 macOS 上 `ipconfig getifaddr en0` 可以通过该命令确认 IP 地址。
3. 点击“打开 Schema”按钮。
4. 如果屏幕顶部 `Bundling {n}%...`显示时，就表示连接成功了。

观看视频

<details>

<summary>手动允许“本地网络”权限的方法</summary>

1. 在 iPhone 的\[设置]应用中 **"Apps in Toss"** 搜索并进入。
2. **"本地网络"** 请打开该选项。

</details>

#### 在 Android 真机或模拟器上运行

1. 用 USB 将 Android 真机连接到电脑。
2. `adb` 通过命令连接端口。

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

   要连接特定设备 `-s` 请添加该选项。

   ```sh
   adb -s {디바이스아이디} reverse tcp:8081 tcp:8081
   adb -s {디바이스아이디} reverse tcp:5173 tcp:5173
   ```
3. 在沙盒应用中输入 scheme 并点击运行按钮。示例： `intoss://kingtoss`
4. 如果屏幕顶部显示打包进度，就表示连接已完成。

\[观看视频]\(../resources/development/local-server/rn-local-develop-android-example.mp4)

<details>

<summary>常用 adb 命令</summary>

```sh
# 断开连接
adb kill-server

# 连接端口
adb reverse tcp:8081 tcp:8081
adb reverse tcp:5173 tcp:5173

# 查看连接状态
adb reverse --list
```

</details>

***

### 7. 调试

#### 准备

React Native Debugger 需要 Chrome 浏览器。如果尚未安装， [请先下载 Chrome 浏览器](https://www.google.com/intl/ko_kr/chrome/)。

#### 使用 Metro 开发服务器调试

在开发服务器运行时，终端中的 `j` 键会打开 React Native Debugger。只有设备与 Metro 服务器连接时才能打开。

调试器提供以下选项卡。

* **Console**: `console.log` 等方式记录的日志，并可在 REPL 环境中直接执行代码。
* **Source**：可以查看正在运行的代码并添加断点。
* **Network**：可以查看网络请求和响应。
* **Memory**：可以分析 Hermes 引擎的内存使用量。
* **Profiler**：可以测量代码执行性能。

**使用 Breakpoints 调试**

要设置断点 `Cmd` + `P`按 Cmd + P 打开文件搜索窗口并选择文件。点击目标行即可添加断点。代码运行到该位置时会停止执行，并可查看当前状态。

在源代码中添加 `debugger` 关键字后，代码会在该位置自动暂停。

**调试异常情况**

**Source 选项卡** 可在右上角 Breakpoints 区域启用以下选项。

* **Pause on uncaught exceptions**：在发生意外异常时自动暂停代码。
* **Pause on caught exceptions**：无论是否已处理，所有异常都会暂停。

{% hint style="info" %}
**请注意**

服务完全停止后，异常 Breakpoints 可能无法正常工作，这是一个 bug。重启开发服务器和 React Native Debugger 即可解决。
{% endhint %}

#### 使用 React DevTools 调试

使用 React DevTools 可以可视化浏览组件结构并进行调试。

如果服务正在运行，请刷新开发模式 RN 视图 `R` 按键进行刷新。出现如下界面时，连接就完成了。

{% hint style="info" %}
**如果使用 Android 设备**

`adb reverse tcp:8097 tcp:8097` 需要通过命令开放端口，React DevTools 才能正常工作。
{% endhint %}

**检查元素**

点击元素选择按钮后，在设备上点选要查看的元素，React DevTools 会直接跳转到该元素。

\[观看视频]\(../resources/learn-more/debugging/inspecting.mp4)

**修改 Prop**

可以查看所选组件的 Prop 并实时修改。双击目标 Prop 后输入值即可立即生效。

\[观看视频]\(../resources/learn-more/debugging/changing-prop.mp4)

#### 故障排查

<details>

<summary>Metro 开发服务器已打开，但显示了 `暂时出问题了` 消息</summary>

可能是没有正确连接到开发服务器。请断开 \`adb\` 连接，然后重新连接 8081、5173 端口。

</details>

<details>

<summary>显示没有可连接的设备</summary>

当 React Native View 出现时，开发服务器和设备就会连接。如果没有可连接的设备，请确认开发服务器是否已正确构建。

</details>

<details>

<summary>REPL 无法运行</summary>

由于 React Native 的 bug，REPL 可能会卡住。请点击 Console 选项卡旁的眼睛图标，在输入框中输入 \`\_\_DEV\_\_\`、\`1\` 等任意代码并执行。

</details>

<details>

<summary>网络检查器无法工作</summary>

网络检查器不支持多实例。如果 socket 连接混乱，请按以下顺序解决。

1. 完全退出应用。
2. 停止开发服务器并关闭网络检查器。
3. 重新启动应用并 `dev` 运行脚本。

如果按此步骤仍无法解决，请向负责人反馈。

</details>

***

### 8. 构建

Bundle 文件是 `.ait` 带有该扩展名的文件，是将构建后的项目打包后的产物。

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

```sh
npm run build
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm build
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn build
```

{% endtab %}
{% endtabs %}

构建完成后，在项目根目录会生成 `<서비스명>.ait` 文件。详细测试方法请参考 [Toss应用](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/toss) 文档。

***

### 9. 发布

发布方法请参考 [迷你应用发布](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/deploy) 文档。


---

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