> 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-migration.md).

# SDK 3.x migration

{% hint style="info" %}
 **`localStorage` Please temporarily hold off on migration when using it.**

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

If you need to preserve existing data, please hold off on SDK 3.x migration 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 data, you can migrate normally.
{% endhint %}

SDK 3.x is an update that improves the structure of WebView projects.\
The config 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 we've changed the SDK's internal processing logic to be handled on the server rather than the client.

Even if SDK issues occur, they can be fixed and applied only on the Apps in Toss server without partner redeployment.\
SDK 3.x is for improving the stability of the mini-app ecosystem and keeping the SDK as a stable version.

***

### Summary of changes

| Item             | Before                                         | After                                             |
| ---------------- | ---------------------------------------------- | ------------------------------------------------- |
| Config file name | `granite.config.ts`                            | `apps-in-toss.config.ts`                          |
| `brand` config   | `displayName`, `primaryColor`, `icon` included | `primaryColor`keep only                           |
| `webViewProps`   | `type` includes properties                     | `webView`renamed to, `type` delete                |
| `outdir`         | `outdir`                                       | `webBundleDir`                                    |
| `web` config     | in the config file `web.commands` included     | 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 use 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

Running the command below will automatically handle the config file conversion and `package.json` script updates.

{% 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` scripts are updated.\
Once migration is complete, please check that the mini-app works properly in the local browser.

***

### Manual migration

`apps-in-toss.config.ts`If it isn't created or the value isn't correct, please check the manual migration guide.

#### 1. Rename the config file

`granite.config.ts` the file name `apps-in-toss.config.ts`change it to.

#### 2. `brand` Config cleanup

`brand` In the config, `primaryColor`delete all properties except

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

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

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

`webViewProps`Rename the name of `webView`to `type` Delete the property.

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

// After
webView: {},
```

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

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

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

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

`web` delete the config block and, `web.commands`the command in `package.json`to

* `web.commands.dev` → `package.json`of `dev` Move it as is into the script.
* `web.commands.build` → `package.json`of `build` move it to the script, but `ait build`add it to run together.

```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. Rollback isn't possible after SDK 3.x release

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

#### 2. CORS changes

From SDK 3.x onward, CORS (Cross-Origin Resource Sharing) changes as follows.\
If you don't 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` : actual 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 there was the inconvenience of having to update again every time the sandbox app was updated.\
From SDK 3.x onward, you can test immediately just by opening the local browser without this process.\
For setup instructions, refer to the test environment below.

***

### Test environment

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

You can check it directly in the local browser using the command below.\
Open the localhost link in the local browser to 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 on SDK 3.0.1, you need to set up AIT Devtools manually. \
Please follow the steps below.

#### 1. Install 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 using Vite `vite.config.ts`add the Devtools plugin to

If using a different bundler, `@apps-in-toss/devtools/unplugin`you need to add it to the config file using the adapter for that bundler provided by. For example `aitDevtools.vite()`, `aitDevtools.webpack()`you can use it like this.

The code below is an example of 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

After running the service, access it using the local browser. If you see AIT Devtools at the bottom right, it is configured correctly, and you can test the mini-app behavior directly 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`to `apps-in-toss.config.ts`renamed it to
* [ ] `brand`in `primaryColor`left only and deleted the rest
* [ ] `webViewProps`to `webView`changed to and `type`deleted
* [ ] `outdir`the `webBundleDir`changed to
* [ ] `web` deleted the config and moved the commands `package.json`to
* [ ] `build` in the script `ait build`includes
* [ ] build works properly
* [ ] checked that it works properly in the test environment (AIT Devtools)
* [ ] uploaded the bundle to the Apps in Toss console
* [ ] completed testing in the Toss app

***

### Inquiry

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