← Blog

앱인토스 SDK 3.x 마이그레이션 — 웹뷰 미니앱 세 개를 2.0.9에서 3.8.0으로 올린 기록

JunGyu Kim · · 16분 읽기앱인토스토스WebViewReact
목차

1. 콘솔이 2.x 번들을 받지 않았습니다

앱인토스는 토스 앱 안에서 돌아가는 미니앱 플랫폼입니다. 제가 만든 웹뷰 미니앱 가운데 이번에 SDK를 올린 앱은 세 개입니다. 1편부터 연재한 차트예측게임, 그리고 나의 성분 분석기와 AI 손금 감정 보고서입니다. 세 앱 모두 @apps-in-toss/web-framework 2.0.9 위에 있었습니다. 차트예측게임은 2026년 3월 24일에 1.x에서 2.x로 올린 지 약 7개월 만에 다시 SDK 메이저 버전을 올리게 됐습니다.

계기는 콘솔이었습니다. 앱인토스 콘솔은 SDK 2.x로 빌드한 웹뷰 번들을 업로드 단계에서 이 문구와 함께 받지 않습니다.

웹뷰 미니앱은 SDK 버전 3.0.0 이상이 필요해요

이미 출시한 앱도 고쳐서 다시 올리려면 SDK부터 올려야 한다는 뜻입니다. 그래서 2026년 10월 14일 하루 동안 세 앱을 그날 기준 최신인 3.8.0으로 올렸습니다. 글에 인용한 공식 가이드 내용은 그날 확인한 것이라 2026년 10월 기준이며, 이후 바뀌었을 수 있습니다. 나머지는 저장소의 커밋과 설치된 패키지, 빌드한 .ait 파일을 근거로 했습니다.

2. .ait 안의 bundle.json으로 SDK 버전 확인하기

빌드가 끝나면 프로젝트 루트에 앱 이름으로 된 .ait 파일이 생기고, 이 파일을 콘솔에 올립니다. .ait는 unzip으로 열 수 있습니다. extra bytes 경고가 뜨지만 내용은 정상적으로 읽힙니다. 3.x 번들에는 bundle.json이 있고, 여기에 SDK 버전이 기록됩니다.

$ unzip -p human-nutrition-facts.ait bundle.json | grep -o '"sdk":{[^}]*}'
warning [human-nutrition-facts.ait]:  2512 extra bytes at beginning or within zipfile
  (attempting to process anyway)
"sdk":{"name":"@apps-in-toss/web-framework","version":"3.8.0"}

sdk 부분만 잘라 낸 것은 bundle.json에 배포 식별자(deploymentId)도 들어 있어서, 통째로 공유하면 식별자까지 나가기 때문입니다. 같이 기록되는 설정(config)은 쓸모가 있습니다. 설정 파일에 webView: {}만 적어도 bundle.json에는 기본값이 펼쳐져 있어, 실제로 묶인 설정을 볼 수 있습니다.

같은 날 낮 12시 22분에 2.0.9로 빌드해 둔 성분 분석기 번들에는 bundle.json이 아예 없었습니다.

$ unzip -p human-nutrition-facts.ait bundle.json   # 2.0.9로 빌드한 번들
warning [human-nutrition-facts.ait]:  3095 extra bytes at beginning or within zipfile
  (attempting to process anyway)
caution: filename not matched:  bundle.json

unzip -l로 두 번들의 파일 목록을 비교하면 구조부터 다릅니다.

2.0.9 번들: 17개 파일, 압축 전 23,029,697바이트
  bundle.ios.0_84_0.js (+ .map)      bundle.android.0_84_0.js (+ .map)
  bundle.ios.0_72_6.js (+ .map)      bundle.android.0_72_6.js (+ .map)
  web/index.html, web/assets/...     웹 결과물 9개
 
3.8.0 번들: 10개 파일, 압축 전 1,576,730바이트
  sources/index.html, sources/assets/...   웹 결과물 8개
  bundle.json
  project-package.json

2.x 번들에는 웹 결과물 말고도 iOS·Android용 JS 번들 네 개와 소스맵 네 개가 있었고, 이 여덟 개가 압축 전 21.5MB로 전체의 93.5%였습니다. 3.x 번들에는 웹 결과물과 메타데이터 두 개만 남았고, project-package.json은 프로젝트의 package.json과 내용이 같았습니다. .ait 크기는 4,226,185바이트에서 600,182바이트로 줄었습니다. 그사이 앱 코드도 바뀌었지만 웹 결과물은 압축 전 1.49MB와 1.58MB로 비슷했으니, 차이는 거의 다 플랫폼 번들에서 나왔습니다.

3. 버전 고르기: SDK 3.1.1 이상, TDS 2.4.1, React 18

콘솔 조건은 3.0.0 이상이지만 공식 가이드는 3.1.1 이상을 쓰라고 합니다. 3.0.0부터 3.1.0까지는 웹뷰의 origin이 바뀌면서 2.x 시절 localStorage 데이터가 사라지기 때문입니다.

설치된 web-framework의 CHANGELOG를 보면 3.1.0에 Migration.getOriginStorage()가 추가됐습니다. 설명은 "Origin이 바뀐 뒤에도 이전 Origin과 현재 Origin의 브라우저 저장소를 함께 확인할 수 있도록"이고, 타입상 이전·현재 origin 각각의 localStorage, IndexedDB, OPFS 내용을 돌려줍니다. 3.1.1에서는 이 반환 타입(OriginStorageDump)을 공개했습니다. 3.1.1 이상에서 데이터가 자동으로 옮겨지는지, 이 API로 직접 옮겨야 하는지는 확인하지 못했습니다. 이 글을 쓰며 세 앱의 작업 전 코드를 다시 보니 localStorage를 쓰는 곳이 없어서 확인할 일이 없었습니다. 2.x에서 localStorage에 데이터를 쌓아 둔 앱이라면 여기부터 보시길 권합니다.

TDS(토스 디자인 시스템)는 가이드가 @toss/tds-mobile과 @toss/tds-mobile-ait 모두 2.4.1을 지정합니다. 당시 npm 최신은 2.5.1이었지만 가이드대로 캐럿 없이 고정했습니다.

"@toss/tds-mobile": "2.4.1",
"@toss/tds-mobile-ait": "2.4.1",

여기서 React가 걸렸습니다. 설치된 TDS 2.4.1의 peerDependencies는 React 18까지만 허용합니다.

"peerDependencies": {
  "@emotion/react": "^11",
  "react": "^16.8.3 || ^17 || ^18",
  "react-dom": "^16.8.3 || ^17 || ^18"
}

성분 분석기와 차트예측게임은 원래 React 18이었지만, 손금 앱은 React 19(잠금 파일 기준 19.2.4)였습니다. 이 상태로 TDS 2.4.1을 설치하면 npm install이 ERESOLVE로 실패합니다. 이 조합은 전부터 삐걱거려서, 손금 앱에는 TDS 타입을 React 19에 맞추는 보정 파일까지 있었습니다.

// src/types/tds-react19-compat.d.ts 첫 부분 (이번에 삭제)
// @toss/tds-mobile 2.x 타입 정의는 React 18에만 있는 ReactHTML, DetailedHTMLFactory를 import해요.
// React 19 타입에는 둘 다 없어서 TDS 버튼 계열의 DOM props(onClick 등)가 사라지므로 최소 형태로 되살려요.

legacy-peer-deps로 밀어붙여 React 19를 지키는 방법은 버렸습니다. 커밋 메시지에 남긴 이유는 TDS가 지원하지 않는 조합이고 다른 두 앱도 React 18이라는 것입니다. react와 react-dom을 ^18.3.1로, 타입 패키지를 ^18.3.27과 ^18.3.7로 내리고 보정 파일을 지웠습니다. React 버전 때문에 고친 컴포넌트 코드는 없었습니다.

Node 경고도 하나 있습니다. 함께 설치되는 @apps-in-toss/devtools 3.8.0과 @apps-in-toss/ait-format 1.0.0은 engines에 Node 24 이상을 적어 두었지만, 로컬 Node 20에서도 ait build는 돌았습니다.

4. npx ait migrate v3가 바꾸는 것

설정 변환은 CLI가 해 줍니다. 5편에서 내비게이션 바를 설정했던 granite.config.ts는 3.x에서 apps-in-toss.config.ts가 됩니다. 설치된 CLI 3.8.0 도움말 기준으로 npx ait migrate v3는 아래 표처럼 설정 파일과 스크립트를 바꾸고, devDependencies에 devtools를 넣어 vite 설정의 plugins 배열 맨 앞에 꽂은 뒤, granite.config를 지우고 패키지 설치까지 실행합니다. 성분 분석기의 실제 변경은 이렇습니다(아이콘 주소 줄만 뺐습니다).

// granite.config.ts (2.x, 마이그레이션 후 삭제)
import { defineConfig } from '@apps-in-toss/web-framework/config';
 
export default defineConfig({
  appName: 'human-nutrition-facts',
  brand: {
    displayName: '나의 성분 분석기',
    primaryColor: '#191f28',
  },
  webViewProps: {
    type: 'partner',
  },
  navigationBar: {
    withBackButton: true,
  },
  web: {
    host: 'localhost',
    port: 5173,
    commands: {
      dev: 'vite',
      build: 'tsc -b && vite build',
    },
  },
  permissions: [],
  outdir: 'dist',
});
// apps-in-toss.config.ts (3.x)
import { defineConfig } from '@apps-in-toss/web-framework/config';
 
export default defineConfig({
  appName: 'human-nutrition-facts',
 
  brand: {
    primaryColor: '#191f28'
  },
 
  webView: {},
 
  navigationBar: {
    withBackButton: true,
  },
 
  permissions: [],
  webBundleDir: 'dist'
});
   "scripts": {
-    "dev": "ait dev",
-    "build": "ait build",
+    "dev": "vite",
+    "build": "tsc -b && vite build && ait build",

성분 분석기와 손금 앱 기준 정리입니다.

항목2.x (2.0.9)3.x (3.8.0)
설정 파일granite.config.tsapps-in-toss.config.ts
branddisplayName, primaryColor, iconprimaryColor만
웹뷰 설정webViewProps (type 포함)webView (type 없음)
결과물 폴더 키outdirwebBundleDir
dev 스크립트ait devvite
build 스크립트ait buildtsc -b && vite build && ait build

빌드 스크립트가 길어진 것은 ait build의 역할이 바뀌어서입니다. 3.x의 ait build는 webBundleDir 폴더를 .ait에 담기만 하고, 도움말도 그 전에 "웹 프레임워크의 빌드 명령(예: vite build)을 먼저 실행"하라고 안내합니다. 2.x에서 granite.config의 web.commands에 맡기던 웹 빌드를 이제 package.json 스크립트가 직접 맡습니다.

brand에서 빠진 앱 이름과 아이콘은 콘솔 등록 정보로 표시되는 것으로 보이지만 직접 확인하지는 못해서, QR 테스트 항목으로 README에 적어 두었습니다. migrate 자체도 성공한 뒤에는 되돌릴 수 없으니 git commit 등으로 상태를 저장해 두라고 도움말이 권합니다. 손금 앱과 성분 분석기는 작업 전에 기준 커밋을 먼저 남겼습니다.

5. devtools 플러그인이 운영 번들에 섞이지 않게

migrate가 꽂아 주는 devtools는 개발 서버에서 SDK를 mock으로 바꿔치기하고 패널을 붙여 줘서, 토스 앱 없이도 브라우저에서 미니앱을 돌려 볼 수 있습니다. 문제는 이것이 운영 빌드에서 켜질 때입니다. 그러면 @apps-in-toss/web-framework import가 mock으로 연결돼 토스 앱 안에서도 SDK 호출이 가짜 구현으로 갑니다. 옵션을 따로 주지 않으면 플러그인이 켜지는 기준은 NODE_ENV 하나입니다.

// @apps-in-toss/devtools 3.8.0, dist/unplugin/index.js
const isDev = process.env.NODE_ENV !== "production";
const shouldEnable = isDev || !!options?.forceEnable;
const shouldMock = shouldEnable && (options?.mock ?? isDev);

보통의 vite build라면 NODE_ENV가 production이 되니 괜찮습니다. 하지만 Vite는 NODE_ENV가 비어 있을 때만 기본값을 채웁니다(설치된 Vite 7.3.1 코드 기준). 셸이나 CI에 NODE_ENV=development가 남아 있으면 빌드 중에도 그 값이 유지되고, 플러그인은 mock을 켭니다. 출시 번들을 환경 변수 하나에 맡기기 싫어서 개발 서버에서만 켜지도록 감쌌습니다.

// vite.config.ts (나의 성분 분석기)
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import aitDevtools from '@apps-in-toss/devtools/unplugin'
 
// Devtools (mock SDK) only on the dev server, never in builds or tests
export default defineConfig(({ command }) => ({
  plugins: [
    ...(command === 'serve' && !process.env.VITEST ? [aitDevtools.vite()] : []),
    react(),
  ],
}))

command는 vite build에서 'build', 개발 서버에서 'serve'라서 빌드할 때는 플러그인이 아예 만들어지지 않습니다. Vitest는 내부에서 Vite 개발 서버를 띄워 설정을 serve로 읽기 때문에, 성분 분석기와 차트예측게임은 VITEST 환경 변수까지 확인합니다. vitest를 쓰지 않는 손금 앱은 command 조건만 둡니다. devtools README에도 같은 command === "serve" 패턴이 실려 있습니다.

차트예측게임은 운영 번들과 테스트 광고 ID를 넣은 QA 번들의 점검 결과를 JSON으로 남겼는데, 두 번들 모두 devtoolsAbsent가 true였습니다.

6. 새 origin의 CORS, 그리고 되돌릴 수 없는 출시

migrate가 끝나면 CLI가 유의사항 세 가지를 띄웁니다. 설치된 CLI 코드에 들어 있는 문구 그대로이며, appName 자리에는 실제 앱 이름이 들어갑니다.

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 테스트 환경
 
3. 개발용 devtools가 함께 설치돼요
   @apps-in-toss/devtools가 devDependencies에 추가됐어요.
   브라우저에서 mock SDK와 devtools 패널로 미니앱을 개발할 수 있어요.

Origin을 제한하는 서버라면 두 주소를 모두 등록해야 합니다. QR 테스트 주소만 넣으면 QR에서 되던 요청이 출시 뒤에 막힐 수 있습니다.

더 무거운 것은 1번입니다. 콘솔에서는 검토 승인이 나도 '출시하기'를 따로 눌러야 출시되므로, 되돌릴 수 없게 되는 순간은 그 버튼입니다. 검토 중인 번들은 하나뿐이라, 고칠 것이 생기면 요청을 취소하고 다시 올려 제출해야 합니다. 반대로 승인과 출시 사이에는 시간이 있습니다. 광고 로드나 Android 하단 여백처럼 실제 토스 앱에서만 확인되는 항목은 출시하기를 누르기 전에 QR로 마저 확인할 수 있습니다.

7. 마이그레이션 체크리스트

  1. 기준 커밋을 남깁니다. migrate는 성공한 뒤 되돌릴 수 없습니다.
  2. 2.x 코드의 localStorage 사용처를 찾고, 있으면 가이드와 Migration.getOriginStorage()를 확인합니다.
  3. web-framework는 3.1.1 이상(저는 3.8.0), TDS 두 패키지는 2.4.1로 고정합니다.
  4. React 19라면 18로 내리고, TDS용 타입 보정 파일이 있다면 지웁니다.
  5. npx ait migrate v3 후 brand, webView, webBundleDir, 스크립트 diff를 검토합니다.
  6. devtools 플러그인은 command === 'serve'일 때만 넣고, Vitest를 쓰면 VITEST도 확인합니다.
  7. 빌드 후 unzip -p로 bundle.json의 SDK 버전을 확인합니다. 공유할 때는 deploymentId를 뺍니다.
  8. Origin을 제한하는 서버에는 https://<appName>.web.tossmini.com과 https://<appName>.private-web.tossmini.com을 모두 허용합니다.
  9. 콘솔 QR로 실기기에서 내비게이션 바 이름·아이콘, 광고, 저장소, API 호출을 확인합니다.
  10. 승인 뒤 '출시하기'는 맨 마지막에 누릅니다. 출시하면 2.x로 돌아갈 수 없습니다.

돌아보면 작업량보다 되돌릴 수 없는 지점을 아는 것이 중요했습니다. migrate 명령은 커밋 하나로 대비할 수 있지만, 출시하기 버튼 뒤에는 2.x로 돌아갈 길이 없어 문제가 생기면 3.x 위에서 고쳐 다시 내야 합니다. 그래서 QR 테스트는 출시 전 마지막 관문으로 두는 편이 안전합니다. 차트예측게임은 앱인토스와 별도로 iOS 앱으로도 출시했습니다.

광고

관련 글