> 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/documentation/api-and-sdk-en/integration/sdk-3.x.md).

# SDK 3.x Migration

{% hint style="info" %}
 **`localStorage` Please hold off on migration for now when in use.**

Browser in SDK 2.x `localStorage`If 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-framework`provided by `Storage` If you are using the API or existing `localStorage` If you do not need to preserve existing data, you can migrate normally.
{% endhint %}

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    | `primaryColor`Only keep                           |
| `webViewProps`          | `type` Include property                          | `webView`rename to, `type` delete                 |
| `outdir`                | `outdir`                                         | `webBundleDir`                                    |
| `web` Configuration     | In the configuration file `web.commands` Include | after deleting `package.json`move to              |
| Test environment        | Sandbox app installation and login required      | Test directly with a local browser (AIT Devtools) |

***

### Package update

First `@apps-in-toss/web-framework`update to version 3.x.

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

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}
{% endtabs %}

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`

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

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}
{% endtabs %}

***

### Automatic migration

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

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

```sh
npx ait migrate v3
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn ait migrate v3
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm ait migrate v3
```

{% endtab %}
{% endtabs %}

After running `apps-in-toss.config.ts` the file is created, and `package.json`of `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.ts`If 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, `primaryColor`delete all properties except for

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

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

#### 3. `webViewProps` → `webView`changed to

`webViewProps`of `webView`rename to, `type` delete the property.

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

// After
webView: {},
```

#### 4. `outdir` → `webBundleDir`changed to

```ts
// Before
outdir: 'dist',

// After
webBundleDir: 'dist',
```

#### 5. `web` After deleting the configuration `package.json`move to

`web` delete the configuration block and, `web.commands`move the commands from `package.json`to

* `web.commands.dev` → `package.json`of `dev` move it into the script as is.
* `web.commands.build` → `package.json`of `build` move it into the script, and `ait build`add it so that it runs together with.

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

***

### Example before and after

#### Before change (granite.config.ts)

```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)

```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.

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

```shellscript
npm run dev
```

{% endtab %}

{% tab title="pnpm" %}

```shellscript
pnpm run dev
```

{% endtab %}

{% tab title="yarn" %}

```shellscript
yarn dev
```

{% endtab %}
{% endtabs %}

***

### 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

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

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

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}
{% endtabs %}

#### 2. Bundler setup

If you are using Vite `vite.config.ts`add the Devtools plugin to

If you are using another bundler, `@apps-in-toss/devtools/unplugin`you 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.

```ts
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.

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

```shellscript
npm run dev
```

{% endtab %}

{% tab title="pnpm" %}

```shellscript
pnpm run dev
```

{% endtab %}

{% tab title="yarn" %}

```shellscript
yarn dev
```

{% endtab %}
{% endtabs %}

***

### Migration checklist

* [ ] `granite.config.ts`the `apps-in-toss.config.ts`renamed it to
* [ ] `brand`in `primaryColor`kept only and deleted the rest
* [ ] `webViewProps`the `webView`changed it to and `type`deleted it
* [ ] `outdir`the `webBundleDir`changed it to
* [ ] `web` deleted the configuration and moved the commands to `package.json`moved to
* [ ] `build` the script includes `ait build`is 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.


---

# 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/documentation/api-and-sdk-en/integration/sdk-3.x.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.