@apps-in-toss/devtools weekly downloads statistics

@apps-in-toss/devtools

앱인토스(Apps in Toss) 미니앱을 일반 브라우저에서 개발·테스트하기 위한 개발 도구예요. @apps-in-toss/web-framework SDK를 mock 구현으로 치환하고, mock 상태를 실시간으로 조작하는 플로팅 패널을 띄우며, 이 둘을 모든 주요 번들러에 배선하는 unplugin 플러그인을 함께 제공해요.

devDependency 전용이에요. 프로덕션 빌드에서는 플러그인이 통째로 비활성화되고, 프로덕션 번들에 기여하는 바이트 수는 0이에요 (아래 프로덕션 빌드 참고).

• mock SDK — check:sdk-exports가 SDK 런타임 export를 전수 대조해요. 현재 2.x 라인 74종(도메인 객체 19개)·3.x 라인 92종(도메인 객체 34개)을 빠짐없이 덮어요. • 플로팅 DevTools 패널 — 12개 탭에서 권한·네트워크·IAP·광고·위치·뷰포트 등 mock 상태를 즉시 전환해요. • 디바이스 시뮬레이션 — iPhone/Galaxy 프리셋 13종 + 프레임/노치/홈 인디케이터/앱인토스 nav bar 오버레이. • 모든 번들러 지원 — Vite · Webpack · Rspack · Rollup · esbuild.

설치

Node 24 이상이 필요해요.

지원 SDK 버전

하나의 패키지가 web-framework 2.x와 3.x를 함께 지원해요. peer 범위는 >=2.6.0 =3.0.1 )는 치환되지 않아요. 메인 엔트리만 대상이에요.

플러그인 옵션

AitDevtoolsOptions의 전부예요.

| 옵션 | 타입 | 기본값 | 설명 |

| panel | boolean | true | 진입점에 @apps-in-toss/devtools/panel import를 자동 주입 | | entryPattern | RegExp | /\/(main\|index\|entry\|app)\.[tj]sx?$/i | 패널 자동 주입 대상 진입점 파일 패턴. 기본 패턴이 매칭하지 않는 파일명(예: 커스텀 브리지 파일)을 쓰는 프로젝트용 — g/y 플래그는 붙이지 마세요 | | sdkVersion | 'auto' \| '2' \| '3' | 'auto' | mock facade 라인 선택. 'auto'는 설치된 SDK 버전을 감지하고, 감지 실패 시 3.x | | forceEnable | boolean | false | production에서도 devtools 활성화 (mock은 기본 OFF, mock: true로 함께 켤 수 있음) | | mock | boolean | true (dev) / false (prod, forceEnable 포함) | SDK alias 활성화 여부 | | initialState | DeepPartial | undefined | mock 상태 초기값 커스터마이즈(예: IAP 상품 카탈로그). DEFAULT_STATE에 재귀 병합 — 객체는 병합, 배열은 통째 교체. Vite 전용 | | mcp | boolean | false | Vite dev 서버에 mock state endpoint 등록 (아래) |

패널 자동 주입은 진입점 파일에만 걸려요 — node_modules 밖의 .ts/.tsx/.js/.jsx 중 파일명이 main · index · entry · app인 것(대소문자 무시). 진입점 이름이 다르면 직접 import하세요.

어디서 돌려서 무엇을 보나

로컬 브라우저 개발이 이 패키지의 주 용도예요. yarn dev로 띄운 데스크톱 브라우저에서 mock SDK가 실제 SDK 자리를 대신하고, 화면 우하단 AIT 버튼으로 패널을 열어 상태를 바꿔요. 토스 앱도 실기기도 필요 없고 HMR이 그대로 살아 있어 반복 주기가 가장 짧아요.

실기기 디버깅은 이 패키지의 범위 밖이며, 별도 패키지 두 개가 담당해요. 토스 앱 WebView에 올라간 미니앱을 원격으로 관측해야 할 때 써요.

• @apps-in-toss/debugger — MCP 디버깅 데몬과 on-device CDP relay를 제공해요. relay는 quick tunnel로 외부 접근 URL을 발급하고, 그 URL을 담은 QR을 띄워 폰이 attach하게 해요. devDependency / npx 전용이라 앱 코드에서 import할 표면 자체가 없어요. • @apps-in-toss/debug-console — 미니앱 안에서 그 relay에 붙는 유일한 런타임 조각이에요. 진입점에 import '@apps-in-toss/debug-console/auto' 한 줄을 넣으면, URL에 ?debug=1과 유효한 ?relay=이 함께 실려 들어온 경우에만 attach해요. 게이트가 막히면 아무것도 하지 않으므로 평범한 프로덕션 로드에는 영향이 없어요.

두 축은 독립적이에요. devtools의 mock·패널은 relay를 필요로 하지 않고, 반대로 실기기 디버깅은 실제 SDK를 상대하므로 mock이 개입하지 않아요. 설치·설정의 정본은 각 패키지 문서예요.

Floating DevTools Panel

@apps-in-toss/devtools/panel을 import하면 DOM이 준비되는 대로 자동 마운트돼요. 마운트는 idempotent라 여러 번 import되거나 mount()를 다시 불러도 토글 버튼은 하나만 남아요. 패널은 React 19 트리지만 React가 dist에 함께 번들되므로, 소비자 프로젝트에 React를 요구하지 않아요.

헤더의 EDIT / READ-ONLY 토글로 편집 가능 여부를 전환할 수 있고, 로케일은 navigator.language로 자동 판별한 뒤 localStorage(__ait_locale)에 저장돼요 — 한국어·영어 카탈로그를 모두 출하해요.

12개 탭

| 탭 | 하는 일 |

| Environment | 플랫폼 OS · 앱 버전 · 운영 환경(toss/sandbox) · 로케일 · 네트워크 · Safe Area · Navigation(no-op API 마지막 호출값) | | Presets | QA 시나리오 preset 적용/해제, 사용자 preset 저장·삭제 | | Viewport | 디바이스 프리셋 + orientation + 프레임/nav bar 오버레이 | | Permissions | camera · photos · geolocation · clipboard · contacts · microphone 권한 상태 전환 | | Notifications | 알림 동의 흐름의 다음 결과 선택 | | Location | 위도 · 경도 · 정확도 설정 | | Device | 디바이스 API 모드 전환, 더미 이미지 추가/제거/초기화 | | IAP | 상품 카탈로그 추가/편집/삭제, 다음 구매 결과, TossPay 결제 결과, 완료 주문 내역 | | Ads | 광고 load/show 트리거와 마지막 광고 이벤트 로그 | | Events | Back/Home 네비게이션 이벤트 트리거, 로그인 상태 토글 | | Analytics | 기록된 분석 이벤트 실시간 로그 뷰어 | | Storage | Storage API로 저장된 항목 조회 및 초기화 |

toss-gated 코드 경로를 dev에서 확인하기

실기기에서 native bridge로만 발화하던 no-op API는 mock이 마지막 호출값을 관측 가능한 상태로 비춰요. 예를 들어 Environment 탭에서 환경을 sandbox → toss로 바꾸면 getOperationalEnvironment() === 'toss'로 게이트된 코드가 실행되고, 그 코드가 부른 setIosSwipeGestureEnabled({ isEnabled: false })의 결과가 Environment 탭 Navigation 섹션에 read-only로 나타나요.

Preset

한 시나리오에 여러 mock 키가 동시에 일정 상태여야 하는 경우를 한 클릭으로 맞춰요. 내장 preset 6종:

| ID | 의미 |

| all-allowed | 모든 권한 허용, WIFI, 로그인됨, IAP success — 기본 시나리오 복귀 | | permission-denied | camera / photos / geolocation / contacts 거부 | | offline | getNetworkStatus → OFFLINE, IAP NETWORK_ERROR, 결제 실패 | | logged-out | auth.isLoggedIn = false | | iap-pending | IAP nextResult → PAYMENT_PENDING | | ads-no-fill | 광고 fill 실패 분기 |

preset이 건드리는 범위는 networkStatus · permissions · auth · iap.nextResult · ads · payment로 좁혀 두었어요 — viewport나 brand 같은 무관한 상태가 함께 흔들리지 않아요. 사용자 preset은 localStorage에 __ait_preset: 한 키씩 저장돼요.

코드에서도 쓸 수 있어요.

디바이스 시뮬레이션 (Viewport 탭)

프리셋을 고르면 CSS 뷰포트 크기, DPR, safe area inset이 함께 적용되고 SafeAreaInsets.get() / .subscribe()가 그 값을 따라가요.

| 카테고리 | 프리셋 |

| Apple | iPhone SE (3rd gen), iPhone 15 Pro, iPhone 16e, iPhone 17, iPhone Air, iPhone 17 Pro, iPhone 17 Pro Max | | Samsung | Galaxy S26, S26+, S26 Ultra, Z Flip7, Z Fold7 (folded / unfolded) | | 기타 | Custom (width/height 직접 입력, 1–4096으로 클램프), None (기본) |

• Orientation — auto이면 앱이 부른 setDeviceOrientation 값을 따르고, portrait/landscape를 고르면 패널이 강제해요. • Show frame — 베젤 · 노치/Dynamic Island/punch-hole · 홈 인디케이터를 그려요. OS 노치는 실기기에서도 WebView 바깥이라 body 위쪽에 그려요. • Apps in Toss nav bar — 호스트 상단 nav bar를 54px로 오버레이해요. partner는 콘텐츠를 그 높이만큼 밀어내고(그래서 SafeAreaInsets.get().top이 곧 nav bar 높이), game은 투명하게 떠서 밀어내지 않아요. • 상태는 sessionStorage(__ait_viewport)에 저장되어 reload 후 복원돼요. • 기기 프리셋이 활성인 동안에는 navigator.userAgent · navigator.platform · devicePixelRatio · screen.*과 getPlatformOS()가 읽는 플랫폼 값을 그 기기 값으로 override해요. none/custom에서는 override하지 않아요.

콘솔에서 직접 조작할 수도 있어요.

한계 — 뷰포트가 활성인 동안에는 스크롤 컨테이너가 window가 아니라 document.body예요. 또한 위 override는 page-JS가 읽는 값만 바꾸며, 실제 CSS media query나 터치 이벤트는 호스트 브라우저 그대로예요. 픽셀·입력 단위까지 정확한 emulation이 필요하면 브라우저 DevTools의 device mode를 쓰세요.

mount / dispose

disposePanel()은 뷰포트 시뮬레이션도 함께 원복해요.

디바이스 API 모드

카메라·앨범·위치는 세 가지 모드로, 네트워크·클립보드는 두 가지 모드로 동작해요.

| 모드 | 동작 | 쓰임 |

| mock | 상태에 저장된 더미 데이터 반환 | 자동화 테스트, 고정 시나리오 | | web | 브라우저 네이티브 API 사용 (Geolocation, File 등) | 실제 브라우저 기능 확인 | | prompt | 패널이 Device 탭을 열고 사용자 입력을 기다림 | 수동 QA |

| 대상 | mock | web | prompt |…

Description from the npm listing.