Integrating the SDK into an Existing Web Project

You can directly install the SDK in an existing web project and convert it into a mini app.

---

1. Install and initialize the SDK

After installing the SDK, initialize the environment.

npm

npm install @apps-in-toss/web-framework
npx ait init

pnpm

pnpm add @apps-in-toss/web-framework
pnpm ait init

yarn

yarn add @apps-in-toss/web-framework
yarn ait init

---

2. Edit the configuration file

When you create the project granite.config.ts is created automatically. appName, displayName, iconPlease change them to match the app information registered in the Apps in Toss console.

import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'my-mini-app', // Enter the appName you entered in the console.
  brand: {
    displayName: 'App Name', // Enter the app name you entered in the console.
    primaryColor: '#FF91D5', // Change this to the app's main color that will be displayed on the screen.
    icon: '', // Enter the URL of the image uploaded in the console. (Right-click the uploaded image in the console's app info and copy the link, then paste it here)
  },
  web: {
    host: 'localhost',
    port: 5173,
    commands: {
      dev: 'vite dev',
      build: 'vite build',
    },
  },
  permissions: [],
  outdir: 'dist',
});

Important

• appNameis used as the unique keythat identifies each app.
• intoss://{appName} It is also used for deep link paths in the form of intoss://{appName} and during testing and deployment.
• Even when testing in the sandbox app, intoss://{appName}you access it with intoss-private://{appName}is used.

---

3. Install TDS

TDS (Toss Design System) WebView With this package, you can easily apply components based on the Toss Design System.

npm

npm install @toss/tds-mobile @toss/tds-mobile-ait @emotion/react@^11 react@^18 react-dom@^18

pnpm

pnpm add @toss/tds-mobile @toss/tds-mobile-ait @emotion/react@^11 react@^18 react-dom@^18

yarn

yarn add @toss/tds-mobile @toss/tds-mobile-ait @emotion/react@^11 react@^18 react-dom@^18

For how to use TDS components and guides, TDS WebView documentationplease check it.

---

4. Run the project

npm

npm run dev

pnpm

pnpm run dev

yarn

yarn dev

---

5. Run the mini app

Once the development server is running, you can view the mini app in the sandbox app. For detailed instructions on testing in the local sandbox app, sandbox app please check the documentation.

Accessing the development server on a physical device

To test on a physical device, when running the bundler --host option, and web.hostmust be set to a network address that can be accessed from the physical device.

import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'ping-pong',
  web: {
    host: '192.168.0.100', // Change to an IP address accessible from the physical device
    port: 5173,
    commands: {
      dev: 'vite --host', // Enable the --host option
      build: 'vite build',
    },
  },
  permissions: [],
});

Once the settings are complete, proceed on the physical device in the following order.

1. Refer to Install the sandbox app and install the sandbox app that matches your device.
2. Change the Metro server address in the sandbox app web.hostto the IP address set in
3. intoss://{appName} Access the mini app via deep link.

---

6. Debugging

Android — Chrome DevTools

Preparation required

To debug on a device, you must first enable USB debugging. Settings → System → About phone → Developer options → Enable USB debugging

1. Run the mini app on an Android emulator or physical device.
2. In the Chrome browser, chrome://inspect/#devices open the page.
3. Under the WebView content to debug in Remote Target inspect select the button.
4. You can debug WebView content just like debugging a normal web page.

iOS — Safari Developer Tools

Preparation required

• You need to enable the Safari Develop menu. Safari Preferences → Advanced tab → Enable the checkbox for Show features for web developers
• To debug on a device, you need to enable Web Inspector. Settings → Safari → Advanced → Enable Web Inspector
• If the device does not appear in the Develop menu, try restarting Safari.

1. Run the mini app on the iOS simulator or physical device.
2. Safari top menu Developer → [Device Name] → [App Name] → [URL - Title]select it.
3. You can debug WebView content just like debugging on the web.

---

7. Build and perform final testing in the Toss app

After development and basic verification in the sandbox app are complete, npm run buildgenerate the app bundle, upload it to the console, and then perform final testing. You must complete testing in the Toss app before you can submit a release request. For details, please refer to Testing in the Toss app documentation.

---

8. Release

For how to release, Mini app release documentation.