开始使用 React Native

如果是第一次开始？

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

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

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

请注意

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

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

---

1. 创建项目

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

npm

npm create granite-app@"^1"

pnpm

pnpm create granite-app@"^1"

yarn

yarn create granite-app@"^1"

1-1. 设置应用名称

应用名称要 kebab-case 格式输入。

my-granite-app

1-2. 选择工具

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

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

1-3. 安装依赖

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

npm

cd my-granite-app
npm install

pnpm

cd my-granite-app
pnpm install

yarn

cd my-granite-app
yarn install

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

---

2. 安装框架

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

npm

npm install @apps-in-toss/framework

pnpm

pnpm add @apps-in-toss/framework

yarn

yarn add @apps-in-toss/framework

---

3. 修改配置文件

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

npm

npx ait init

pnpm

pnpm ait init

yarn

yarn ait init

1. 请选择框架。
2. 应用名称(appName)请输入。请与在 Apps in Toss 控制台注册的名称保持一致。

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

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 设计系统的组件。

npm

npm install @toss/tds-react-native

yarn

yarn add @toss/tds-react-native

pnpm

pnpm add @toss/tds-react-native

TDS 组件的使用方法和指南请查看 TDS React Native 文档。

无法在本地测试 TDS

TDS 无法在本地浏览器中运行。 沙盒应用请通过它进行测试。

---

5. 启动开发服务器

npm

npm run dev

pnpm

pnpm dev

yarn

yarn dev

Metro 开发服务器启动后，可以在沙盒应用中查看迷你应用。关于在沙盒应用中测试的详细方法，请参考 沙盒应用 文档。

如果出现 too many open files 错误

请删除 node_modules 目录后重新安装依赖。

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

---

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}%...显示时，就表示连接成功了。

观看视频

手动允许“本地网络”权限的方法

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

在 Android 真机或模拟器上运行

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

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

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

   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)

常用 adb 命令

# 断开连接
adb kill-server

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

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

---

7. 调试

准备

React Native Debugger 需要 Chrome 浏览器。如果尚未安装， 请先下载 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：无论是否已处理，所有异常都会暂停。

请注意

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

使用 React DevTools 调试

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

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

如果使用 Android 设备

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

检查元素

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

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

修改 Prop

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

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

故障排查

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

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

显示没有可连接的设备

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

REPL 无法运行

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

网络检查器无法工作

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

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

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

---

8. 构建

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

npm

npm run build

pnpm

pnpm build

yarn

yarn build

构建完成后，在项目根目录会生成 <서비스명>.ait 文件。详细测试方法请参考 Toss应用 文档。

---

9. 发布

发布方法请参考 迷你应用发布 文档。