> 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/development/sdk-3.x.md).

# SDK 3.x 마이그레이션

SDK 3.x는 WebView 프로젝트의 구조를 개선한 업데이트예요.\
설정 파일 이름과 일부 프로퍼티가 변경되며, 클라이언트 SDK가 고도화됐어요.\
파라미터와 반환값은 SDK 2.x와 동일하고, SDK 내부 처리 로직을 클라이언트가 아닌 서버에서 처리하도록 변경했어요.

SDK 이슈가 발생해도 파트너사의 재배포 없이 앱인토스 서버에서만 수정하고 반영할 수 있어요.\
SDK 3.x는 미니앱 생태계의 안정성을 높이고, SDK를 안정적인 버전으로 유지하기 위해서예요.

***

## 변경 사항 요약

| 항목             | 변경 전                                     | 변경 후                        |
| -------------- | ---------------------------------------- | --------------------------- |
| 설정 파일 이름       | `granite.config.ts`                      | `apps-in-toss.config.ts`    |
| `brand` 설정     | `displayName`, `primaryColor`, `icon` 포함 | `primaryColor`만 유지          |
| `webViewProps` | `type` 프로퍼티 포함                           | `webView`로 이름 변경, `type` 삭제 |
| `outdir`       | `outdir`                                 | `webBundleDir`              |
| `web` 설정       | 설정 파일 내 `web.commands` 포함                | 삭제 후 `package.json`으로 이동    |

***

## 패키지 업데이트

먼저 `@apps-in-toss/web-framework`를 3.x 버전으로 업데이트해요.\
`@rc` 태그는 현재 3.0을 가리켜요.

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

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}
{% endtabs %}

TDS(Toss Design System)를 사용하는 경우, 아래 2가지를 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 %}

***

## 자동 마이그레이션

아래 명령어를 실행하면 설정 파일 변환과 `package.json` 스크립트 업데이트가 자동으로 처리돼요.

{% 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 %}

실행 후 `apps-in-toss.config.ts` 파일이 생성되고, `package.json`의 `dev`, `build` 스크립트가 업데이트돼요.\
마이그레이션이 완료되면 빌드 후 앱인토스 콘솔에 번들을 업로드해서 토스앱에서 테스트해 주세요.

{% hint style="info" %}
**자동 마이그레이션이 실패한 경우**

`apps-in-toss.config.ts`가 생성되지 않거나 값이 올바르지 않으면 아래 수동 마이그레이션을 따르세요.
{% endhint %}

***

## 수동 마이그레이션

### 1. 설정 파일 이름 변경

`granite.config.ts` 파일 이름을 `apps-in-toss.config.ts`로 변경하세요.

### 2. `brand` 설정 정리

`brand` 설정에서 `primaryColor`를 제외한 나머지 프로퍼티를 삭제하세요.

```ts
// 변경 전
brand: {
  displayName: '앱 이름',
  primaryColor: '#3182F6',
  icon: 'https://...',
},

// 변경 후
brand: {
  primaryColor: '#3182F6',
},
```

### 3. `webViewProps` → `webView`로 변경

`webViewProps`의 이름을 `webView`로 바꾸고, `type` 프로퍼티를 삭제하세요.

```ts
// 변경 전
webViewProps: {
  type: 'partner',
},

// 변경 후
webView: {},
```

### 4. `outdir` → `webBundleDir`로 변경

```ts
// 변경 전
outdir: 'dist',

// 변경 후
webBundleDir: 'dist',
```

### 5. `web` 설정 삭제 후 `package.json`으로 이동

`web` 설정 블록을 삭제하고, `web.commands`에 있던 커맨드를 `package.json`으로 옮기세요.

* `web.commands.dev` → `package.json`의 `dev` 스크립트에 그대로 옮겨요.
* `web.commands.build` → `package.json`의 `build` 스크립트에 옮기되, `ait build`를 함께 실행하도록 추가해요.

```json
// package.json 변경 예시
{
  "scripts": {
    "dev": "vite --port 3000",
    "build": "vite build && ait build"
  }
}
```

***

## 변경 전후 예시

### 변경 전(granite.config.ts)

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

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

### 변경 후(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',
});
```

***

## 유의사항

### 1. SDK 3.x 출시 후 롤백이 안돼요

SDK 3.x 이상이 적용된 앱 번들을 출시하면 SDK 2.x 버전으로 롤백할 수 없어요.\
QR코드로 충분히 테스트한 후 출시해 주세요.

### 2. CORS가 변경돼요

SDK 3.x 버전부터는 CORS(Cross-Origin Resource Sharing)가 아래와 같이 변경돼요.\
Origin 허용 목록에 다음 도메인을 등록하지 않으면 API 요청이 차단될 수 있어요. Origin 허용 목록에 다음 도메인을 등록하세요.

* `https://<appName>.web.tossmini.com` : 실제 서비스 환경
* `https://<appName>.private-web.tossmini.com` : 콘솔 QR 테스트 환경

***

## 마이그레이션 체크리스트

* [ ] `granite.config.ts`를 `apps-in-toss.config.ts`로 이름 변경했어요
* [ ] `brand`에서 `primaryColor`만 남기고 나머지를 삭제했어요
* [ ] `webViewProps`를 `webView`로 변경하고 `type`을 삭제했어요
* [ ] `outdir`을 `webBundleDir`로 변경했어요
* [ ] `web` 설정을 삭제하고 커맨드를 `package.json`으로 옮겼어요
* [ ] `build` 스크립트에 `ait build`가 포함되어 있어요
* [ ] 빌드가 정상 동작해요
* [ ] 앱인토스 콘솔에 번들을 업로드했어요
* [ ] 토스앱에서 테스트를 완료했어요

***

## 문의

마이그레이션 관련 문의는 채널톡 또는 커뮤니티를 통해 문의해 주세요.


---

# 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/development/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.