> 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" %}
**如果是第一次开始？**

如果你是第一次进行 App in Toss 开发，或者想借助 AI 快速制作迷你应用，请先阅读“使用 AI 制作迷你应用”文档。
{% endhint %}

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

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

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

需要原生模块的库，只能在 App 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`：分别负责代码格式化和 lint。通过细致的配置和丰富的插件，支持灵活的代码质量管理。
* `biome`：基于 Rust 的快速一体化格式化·lint 工具。通过简单配置即可高效工作。

#### 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. 安装框架

要使用 App 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`)请填写与 App in Toss 控制台中注册的名称一致。

初始化完成后，项目根目录会生成 `granite.config.ts` 文件。 `appName`, `displayName`, `icon`请修改为与 App 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>', // 请改为在 App in Toss 控制台注册的应用名称。
  plugins: [
    appsInToss({
      brand: {
        displayName: '应用名称', // 请改为在界面上显示的应用韩文名称。
        primaryColor: '#3182F6', // 请改为在界面上显示的应用主色。
        icon: null, // 请输入在控制台上传的图片 URL。（在控制台的应用信息中右键点击已上传的图片，复制链接后填入）
      },
      permissions: [],
    }),
  ],
});
```

***

### 4. 安装 TDS

**TDS(Toss Design System) React Native** 使用该包可以轻松应用基于 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 %}

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，然后点击“打开 Scheme”按钮。例： `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. 点击“打开 Scheme”按钮。
4. 当屏幕顶部 `Bundling {n}%...`显示时，说明连接成功。

观看视频

<details>

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

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

</details>

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

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

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

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

   ```sh
   adb -s {设备ID} reverse tcp:8081 tcp:8081
   adb -s {设备ID} 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 可能无法正常工作，这是一个已知问题。重启开发服务器和 React Native Debugger 即可解决。
{% endhint %}

#### 使用 React DevTools 调试

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

如果服务正在运行，请按开发模式 RN 视图的 `R` 键刷新。出现如下画面时，说明连接已完成。

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

`需要通过 adb reverse tcp:8097 tcp:8097 命令开放端口，React DevTools 才能正常工作。` 命令开放端口，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 可能会卡住。请点击控制台标签旁的眼睛图标，在输入框中输入 \`\_\_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.