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

설치

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

Node 24 이상이 필요해요.

지원 SDK 버전

하나의 패키지가 web-framework 2.x와 3.x를 함께 지원해요. peer 범위는 >=2.6.0 <3.0.0 || >=3.0.1 <4.0.0이고 optional이에요 — 패널만 쓰는 프로젝트라면 SDK를 설치하지 않아도 돼요.

SDK 라인	facade 자동 선택	수동 지정 시 alias 대상
2.x	unplugin이 설치 버전을 읽어 감지	@apps-in-toss/devtools/mock/2x
3.x	위와 동일 (감지 실패 시 기본값)	@apps-in-toss/devtools/mock/3x

자동 감지는 소비자 프로젝트의 @apps-in-toss/web-framework/package.json 버전을 읽어요. monorepo처럼 해석이 애매한 환경에서는 sdkVersion: '2' | '3'으로 못박으세요.

번들러 배선

Vite

// vite.config.ts
import aitDevtools from "@apps-in-toss/devtools/unplugin";

export default {
  plugins: [aitDevtools.vite()],
};

Webpack / Rspack / Rollup / esbuild

같은 default export에서 번들러별 팩토리를 꺼내 써요. unplugin 엔트리는 ESM·CJS를 모두 출하하므로 require도 돼요.

// webpack.config.js (ESM)
import aitDevtools from "@apps-in-toss/devtools/unplugin";
config.plugins.push(aitDevtools.webpack());

// webpack.config.js (CommonJS)
const aitDevtools = require("@apps-in-toss/devtools/unplugin");
config.plugins.push(aitDevtools.webpack());

aitDevtools.rspack() · aitDevtools.rollup() · aitDevtools.esbuild()도 같은 방식이에요.

플러그인이 없는 환경 — 수동 alias

Turbopack처럼 unplugin을 지원하지 않는 번들러에서는 resolve alias로 직접 지정해요.

// vite.config.ts
export default {
  resolve: {
    alias: {
      "@apps-in-toss/web-framework": "@apps-in-toss/devtools/mock",
    },
  },
};

@apps-in-toss/web-framework 하나만 alias하면 충분해요 — SDK 호출은 모두 이 패키지를 거치므로, 치환하는 순간 원본 모듈과 그것이 끌어오던 @apps-in-toss/webview-bridge가 모듈 그래프에서 함께 빠져요. 2.x 라인이면 alias 대상을 @apps-in-toss/devtools/mock/2x로 바꾸세요.

수동 alias만 쓰면 패널이 자동 주입되지 않아요. 진입점에 직접 추가하세요.

import "@apps-in-toss/devtools/panel";

플러그인이 인터셉트하는 모듈

import 스펙	치환 대상
@apps-in-toss/web-framework	감지된 라인의 mock facade
@apps-in-toss/webview-bridge	3.x mock facade
@apps-in-toss/web-bridge	2.x mock facade (back-compat)
@apps-in-toss/web-analytics	2.x mock facade (back-compat)

서브패스 import(@apps-in-toss/web-framework/<subpath>)는 치환되지 않아요. 메인 엔트리만 대상이에요.

플러그인 옵션

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<MockState>	undefined	mock 상태 초기값 커스터마이즈(예: IAP 상품 카탈로그). DEFAULT_STATE에 재귀 병합 — 객체는 병합, 배열은 통째 교체. 기본 상태에 없는…