적용 가능 여부

이 디버거를 다른 프로젝트에 이식하기 전에, 그 프로젝트가 요구사항을 만족하는지 먼저 확인하세요. 결론부터 말하면 Vue 3 + 빌드 도구(번들러)가 있는 앱이면 거의 어디서나 동작합니다. 추가로 깔아야 할 라이브러리도, 설정해야 할 별도 인프라도 없습니다.

이 페이지는 "붙일 수 있는가"를 5분 안에 판단하는 체크리스트입니다. 호환되는 것을 확인했다면 설치와 연동으로 넘어가세요.

한눈에 보는 요구사항 매트릭스

각 항목이 왜 필요한지와, 내 프로젝트가 충족하는지 어디서 확인하는지까지 함께 정리했습니다.

항목	요구	확인 방법
Vue	3.4 이상	package.json의 vue 버전
번들러	Vite 권장(필수는 아님). webpack·Vue CLI도 가능	vite.config.* 또는 vue.config.js 존재
상태/라우터	pinia·vue-router는 있으면 자동 연동, 없어도 동작	선택 — 없어도 무방
환경	브라우저(모바일 WebView 포함). SSR 서버 측에선 자동 비활성	—

Vue는 왜 3.4 이상인가

디버거는 Vue 3의 인스펙션 API에 의존하며, vue(^3.4.0)를 유일한 peerDependency로 선언합니다. 호스트 앱의 vue를 그대로 사용하므로 vue를 중복 설치하지 않습니다. 버전은 다음으로 확인하세요.

npm ls vue

3.4.0 미만이라면 먼저 vue를 올린 뒤 진행하세요.

번들러는 Vite를 권장하지만 강제는 아닙니다

이 도구가 개발/검증 환경에서만 코드에 포함되고 프로덕션에선 통째로 제거되는 핵심 메커니즘은 번들러의 정적 환경변수 치환(import.meta.env)과 dead-code 제거에 기댑니다. Vite는 이 동작이 기본값이라 가장 매끄럽습니다.

webpack·Vue CLI 기반 프로젝트에는 import.meta.env가 없으므로, 활성 분기를 process.env.NODE_ENV !== "production"으로 대체합니다. 구체적인 코드는 연동과 환경별 설정에서 다룹니다.

pinia·vue-router·axios가 없어도 됩니다

디버거는 pinia·vue-router·axios를 import하지 않습니다. 대신 런타임에 이들을 구조적으로 발견만 합니다. 따라서 이 라이브러리들이 없는 프로젝트에서도 디버거는 정상 동작하고, 발견하지 못한 경우 해당 패널(예: Pinia 패널·Router 패널)이 빈 상태로 표시될 뿐 오류가 나지 않습니다.

덕분에 디버거의 런타임 의존성은 0개이며, 어떤 상태관리·라우팅 스택을 쓰든 그대로 이식할 수 있습니다.

pinia·router 자동 발견이 실패하면

드물게 빌드 구성에 따라 자동 발견이 안 될 수 있습니다. 그럴 때만 attachDebugger(app, { pinia, router })로 인스턴스를 수동 주입하세요(보통 불필요). 전체 옵션은 옵션 레퍼런스를 참고하세요.

실행 환경

이 도구는 브라우저 런타임 전용입니다. 그 안에서도 특히 모바일을 우선합니다.

• 브라우저 + 모바일 WebView: 모든 기능이 페이지 안에서 동작하도록 설계됐습니다. 브라우저 확장을 설치할 수 없는 환경(사내 보안 정책 등)이나, devtools 자체가 없는 모바일 WebView에서도 페이지 안의 FAB(⚙)와 Alt+Shift+D 단축키로 디버거를 엽니다. WebView에서는 이 도구가 사실상 유일한 디버깅 수단입니다.
• Shadow DOM 격리: 디버거 UI는 Shadow DOM으로 호스트 앱과 완전히 격리됩니다. 그래서 CSS import가 필요 없고(스타일이 Shadow DOM 안에 자동 주입됨) 호스트 앱의 CSS와 충돌하지 않습니다.

SSR(서버 사이드 렌더링)에서는

서버 측 렌더링 단계에서는 디버거가 자동으로 비활성화됩니다. 진입점 attachDebugger(app, options)는 비브라우저 환경에서 핸들을 만들지 않고 null을 반환하므로, SSR 빌드를 깨뜨리지 않습니다. 브라우저로 하이드레이션된 뒤 클라이언트에서만 동작합니다.

프로덕션에는 들어가지 않습니다

가장 자주 받는 우려, "검증용 디버거가 진짜 배포본에 섞여 들어가지 않느냐"에 대한 답입니다.

디버거를 붙이는 코드는 정적으로 판별 가능한 분기 안에 둡니다.

if (import.meta.env.DEV || (import.meta.env.MODE === 'staging' && import.meta.env.VITE_DEBUGGER === 'on')) {
  const { attachDebugger } = await import('@platform/vue-debugger')
  attachDebugger(app)
}

프로덕션 빌드에서는 이 분기 조건이 정적으로 false로 치환되고, 그 결과 안쪽의 동적 import() 블록이 dead-code로 통째 제거됩니다. 즉 진짜 프로덕션 번들에는 디버거 코드가 한 줄도 들어가지 않습니다.

동적 키 접근은 금지

환경변수를 import.meta.env['VITE_DEBUGGER']처럼 동적으로 읽으면 번들러가 정적 치환을 못 해 dead-code 제거가 무력화되고, 디버거가 프로덕션 번들에 그대로 남을 수 있습니다. 반드시 위 예시처럼 정적 속성 접근(import.meta.env.VITE_DEBUGGER)을 사용하세요.

이 활성 분기와 bootstrap()을 async 함수로 감싸야 하는 이유(top-level await 함정)는 연동에서, 빌드별 플래그는 환경별 설정에서 자세히 다룹니다.

다음 단계

요구사항을 모두 확인했다면 설치로 넘어가세요.

• 먼저 빠르게 띄워 보고 싶다면 → 빠른 시작
• 패키지를 설치하려면 → 설치
• 부트스트랩에 연동하려면 → 연동