정적 JS 파일 빌드 및 문제 해결 가이드

이 문서는 aptabase.min.js와 aptabase.debug.js 파일을 빌드하고, 빌드 과정에서 발생한 문제들을 해결하는 과정을 기록합니다.

초기화 및 이벤트 전송

기본 사용법

trackEvent 함수를 사용하여 이벤트를 전송할 때, 두 번째 인자로 JavaScript 객체를 전달하여 사용자 정의 속성(props)을 함께 보낼 수 있습니다. props 객체의 값으로는 문자열, 숫자, 불리언 타입이 가능합니다.

예제:

<script>
  // Aptabase 초기화
  window.aptabase.init("YOUR_APP_KEY");

  function track(eventName, props) {
    // 이벤트와 함께 props 전송
    window.aptabase.trackEvent(eventName, props);
    console.log(`Event '${eventName}' sent!`, props ? { props } : '');
  }
</script>

<!-- props 없이 이벤트 전송 -->
<button onclick="track('app_started')">Track: App Started</button>

<!-- props와 함께 이벤트 전송 -->
<button onclick="track('feature_a_used', { plan: 'premium', from: 'sidebar' })">Track: Used Feature A</button>
<button onclick="track('item_purchased', { item_id: 'SKU-123', price: 9.99, on_sale: true })">Track: Item Purchased</button>

Self-Hosted 환경 초기화

자체 호스팅(Self-hosting) 환경의 Aptabase를 사용하는 경우, init 함수의 두 번째 인자로 host 옵션을 반드시 전달해야 합니다. Self-hosted용 App Key는 일반적으로 SH 지역 코드를 포함합니다.

예제:

<script>
  // Self-Hosted용 App Key와 host 주소를 사용하여 초기화
  window.aptabase.init("A-SH-YOUR_UNIQUE_ID", {
    host: "https://your-aptabase-instance.com"
  });

  function track(eventName, props) {
    window.aptabase.trackEvent(eventName, props);
    console.log(`Event '${eventName}' sent!`);
  }
</script>

빌드 문제 해결 과정

1. `tsup` 빌드 설정 수정

문제: 초기 tsup.config.ts 설정은 aptabase.min.js와 aptabase.debug.js를 명시적으로 생성하지 않아 minify 과정에서 문제가 발생할 가능성이 있었습니다.
해결: tsup.config.ts 파일을 수정하여 디버그와 minify 버전을 각각 다른 define 설정을 통해 생성하도록 빌드 구성을 분리했습니다.

2. `pnpm` 워크스페이스 설정

문제: pnpm을 사용하는 모노레포 환경에서 pnpm install을 실행했음에도 tsup 명령어를 찾지 못하는 문제가 발생했습니다.
원인: pnpm-workspace.yaml 파일이 없어 pnpm이 워크스페이스를 올바르게 인식하지 못했습니다.
해결: 프로젝트 루트에 pnpm-workspace.yaml 파일을 생성하고 packages와 examples 디렉토리를 워크스페이스로 지정한 후, pnpm install을 다시 실행하여 의존성을 올바르게 설치했습니다.

3. 타입 정의(Typings) 문제 해결

문제: 빌드 중 Cannot find name 'chrome' 및 Cannot find name 'process'와 같은 타입스크립트 컴파일 오류가 발생했습니다.
원인: 브라우저 및 Node.js 환경에서만 제공되는 전역 객체(chrome, process)에 대한 타입 정의가 없었습니다.
해결:
1. @types/chrome과 @types/node 패키지를 개발 의존성으로 설치했습니다.
2. packages/web/tsconfig.json의 compilerOptions.types 배열에 "chrome"과 "node"를 추가하여 타입스크립트가 해당 타입들을 인식하도록 설정했습니다.

4. `process` is not defined` 런타임 오류 해결

문제: 빌드된 aptabase.min.js 파일을 브라우저에서 실행할 때 ReferenceError: process is not defined 런타임 오류가 발생했습니다.
원인: 소스코드(shared.ts, index.ts)에서 process.env.NODE_ENV와 process.env.PKG_VERSION을 참조하고 있었고, 이 코드가 브라우저 환경에서 실행<EC8BA4><ED9689>면서 process 객체를 찾지 못해 오류가 발생했습니다.
해결: tsup.config.ts의 define 옵션을 사용하여 빌드 시점에 해당 환경 변수들을 실제 값으로 교체하도록 설정했습니다.
- aptabase.min.js (프로덕션용): process.env.NODE_ENV를 'production'으로 설정
- aptabase.debug.js (디버그용): process.env.NODE_ENV를 'development'로 설정

최종 빌드 방법

위의 모든 문제 해결 후, 다음 명령어를 사용하여 성공적으로 aptabase.min.js와 aptabase.debug.js 파일을 빌드할 수 있습니다.

# 프로젝트 루트 디렉토리에서 실행
pnpm --filter @aptabase/web build

4.6 KiB Raw Permalink Blame History Unescape Escape