SDK 3.x migration

localStorage Please hold off on migration for now when in use.

Browser in SDK 2.x localStorageIf you are using it directly, migrating to SDK 3.x means the existing localStorage data cannot be accessed.

If you need to preserve existing data, please hold off on migrating to SDK 3.x until further notice.

@apps-in-toss/web-frameworkprovided by Storage If you are using the API or existing localStorage If you do not need to preserve existing data, you can migrate normally.

SDK 3.x is an update that improves the structure of the WebView project. The configuration file name and some properties have changed, and the client SDK has been enhanced. The parameters and return values are the same as SDK 2.x, and the internal processing logic in the SDK has been changed so that it is handled on the server instead of the client.

Even if an SDK issue occurs, it can be fixed and applied only on the Apps in Toss server without the partner company having to redistribute it. SDK 3.x is intended to improve the stability of the mini-app ecosystem and keep the SDK on a stable version.

---

Summary of changes

Item	Before	After
Configuration file name	granite.config.ts	apps-in-toss.config.ts
brand Configuration	displayName, primaryColor, icon Include	primaryColorOnly keep
webViewProps	type Include property	webViewrename to, type delete
outdir	outdir	webBundleDir
web Configuration	In the configuration file web.commands Include	after deleting package.jsonmove to
Test environment	Sandbox app installation and login required	Test directly with a local browser (AIT Devtools)

---

Package update

First @apps-in-toss/web-frameworkupdate to version 3.x.

npm

npm install @apps-in-toss/web-framework

yarn

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

pnpm

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

If you are using TDS (Toss Design System), please update the two items below to version 2.4.1.

• @toss/tds-mobile
• @toss/tds-mobile-ait

npm

npm install @toss/tds-mobile@2.4.1 @toss/tds-mobile-ait@2.4.1

yarn

yarn add @toss/tds-mobile@2.4.1 @toss/tds-mobile-ait@2.4.1

pnpm

pnpm add @toss/tds-mobile@2.4.1 @toss/tds-mobile-ait@2.4.1

---

Automatic migration

If you run the command below, the configuration file conversion and package.json script update will be handled automatically.

npx

npx ait migrate v3

yarn

yarn ait migrate v3

pnpm

pnpm ait migrate v3

After running apps-in-toss.config.ts the file is created, and package.jsonof dev, build the script is updated. When the migration is complete, please check whether the mini-app works properly in the local browser.

---

Manual migration

apps-in-toss.config.tsIf the file is not created or the value is incorrect, please check the manual migration guide.

1. Rename the configuration file

granite.config.ts Change the file name to apps-in-toss.config.ts.

2. brand Clean up the configuration

brand In the configuration, primaryColordelete all properties except for

// Before
brand: {
  displayName: 'App name',
  primaryColor: '#3182F6',
  icon: 'https://...',
},

// After
brand: {
  primaryColor: '#3182F6',
},

3. webViewProps → webViewchanged to

webViewPropsof webViewrename to, type delete the property.

// Before
webViewProps: {
  type: 'partner',
},

// After
webView: {},

4. outdir → webBundleDirchanged to

// Before
outdir: 'dist',

// After
webBundleDir: 'dist',

5. web After deleting the configuration package.jsonmove to

web delete the configuration block and, web.commandsmove the commands from package.jsonto

• web.commands.dev → package.jsonof dev move it into the script as is.
• web.commands.build → package.jsonof build move it into the script, and ait buildadd it so that it runs together with.

// Example of package.json changes
{
  "scripts": {
    "dev": "vite --port 3000",
    "build": "vite build && ait build"
  }
}

---

Example before and after

Before change (granite.config.ts)

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

export default defineConfig({
  appName: 'my-app',
  brand: {
    displayName: 'My app',
    primaryColor: '#3182F6',
    icon: 'https://...',
  },
  web: {
    host: 'localhost',
    port: 3000,
    commands: {
      dev: 'vite --port 3000',
      build: 'vite build',
    },
  },
  webViewProps: {
    type: 'partner',
  },
  permissions: [],
  outdir: 'dist',
});

After change (apps-in-toss.config.ts)

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

export default defineConfig({
  appName: 'my-app',
  brand: {
    primaryColor: '#3182F6',
  },
  webView: {},
  permissions: [],
  webBundleDir: 'dist',
});

---

Notes

1. You cannot roll back after releasing SDK 3.x

If you release an app bundle with SDK 3.x or later applied, you cannot roll back to SDK 2.x. Please test thoroughly with the QR code before releasing.

2. CORS changes

Starting with SDK 3.x, CORS (Cross-Origin Resource Sharing) changes as follows. If you do not register the following domains in the Origin allowlist, API requests may be blocked. Register the following domains in the Origin allowlist.

• https://<appName>.web.tossmini.com : production environment
• https://<appName>.private-web.tossmini.com : console QR test environment

3. A new test environment is provided

Previously, you had to install and log in to the sandbox app, and it was inconvenient because you had to update it again every time the sandbox app was updated. Starting with SDK 3.x, you can test right away by simply opening a local browser, without that process. For setup instructions, see the test environment below.

---

Test environment

If you scaffolded a new project or migrated from version 2.x to 3.x, AIT Devtools is configured automatically.

You can check it right away through the local browser using the command below. Open the localhost link in the local browser and check whether the mini-app works.

npm

npm run dev

pnpm

pnpm run dev

yarn

yarn dev

---

Manual test environment setup

If you migrated from SDK 3.0.1, you need to configure AIT Devtools manually. Please follow the steps below to set it up.

1. Install the package

npm

npm install -D @apps-in-toss/devtools

pnpm

pnpm add -D @apps-in-toss/devtools

yarn

yarn add -D @apps-in-toss/devtools

2. Bundler setup

If you are using Vite vite.config.tsadd the Devtools plugin to

If you are using another bundler, @apps-in-toss/devtools/unpluginyou must use the adapter for that bundler provided by and add it to the configuration file. For example, aitDevtools.vite(), aitDevtools.webpack()can be used like this.

The code below is an example configuration when using the Vite bundler.

import aitDevtools from "@apps-in-toss/devtools/unplugin";

export default defineConfig({
  plugins: [
    aitDevtools.vite(),
    react(),
    babel({ presets: [reactCompilerPreset()] }),
  ],
});

3. Test it

After running the service, access it through the local browser. If you see AIT Devtools in the lower right corner, it is set up correctly, and you can test the mini-app behavior right on this screen.

npm

npm run dev

pnpm

pnpm run dev

yarn

yarn dev

---

Migration checklist

• granite.config.tsthe apps-in-toss.config.tsrenamed it to
• brandin primaryColorkept only and deleted the rest
• webViewPropsthe webViewchanged it to and typedeleted it
• outdirthe webBundleDirchanged it to
• web deleted the configuration and moved the commands to package.jsonmoved to
• build the script includes ait buildis included
• the build works properly
• confirmed it works properly in the test environment (AIT Devtools)
• uploaded the bundle to the Apps in Toss console
• completed testing in the Toss app

---

Contact

For migration-related inquiries, please contact us via Channel Talk or the community.