@imqa/vite-sourcemap

Vite 플러그인으로 빌드 후 소스맵을 자동으로 업로드합니다. IMQA 서비스에 소스맵을 업로드하여 프로덕션 환경에서 발생한 에러의 원본 소스코드 위치를 추적할 수 있습니다.

기능

• Vite 빌드 완료 후 소스맵 자동 업로드
• 멀티파트 폼 데이터로 파일 업로드
• 포함/제외 패턴으로 파일 필터링
• gzip 압축 지원
• 동시 업로드 제한 및 재시도 로직
• CI 환경 감지
• 업로드 후 로컬 소스맵 파일 삭제 옵션
• 커스텀 경로 변환 및 URL 접두사 지원

설치

npm install @imqa/vite-sourcemap --save-dev

사용법

기본 설정

// vite.config.ts
import { defineConfig } from 'vite'
import sourcemapUpload from '@imqa/vite-sourcemap'

export default defineConfig({
  build: {
    sourcemap: true, // 중요: 소스맵 생성을 활성화해야 합니다
  },
  plugins: [
    sourcemapUpload({
      endpoint: 'https://api.your-service.imqa.io/api/sourcemaps',
      apiKey: process.env.SOURCEMAP_API_KEY,
      release: process.env.GIT_SHA,
      appVersion: process.env.npm_package_version,
    }),
  ],
})

고급 설정

// vite.config.ts
import { defineConfig } from 'vite'
import sourcemapUpload from '@imqa/vite-sourcemap'

export default defineConfig({
  build: {
    sourcemap: true,
  },
  plugins: [
    sourcemapUpload({
      // 필수: 업로드 엔드포인트
      endpoint: 'https://api.your-service.imqa.io/api/sourcemaps',
      
      // 인증
      apiKey: process.env.SOURCEMAP_API_KEY,
      
      // 릴리즈 정보
      release: process.env.GIT_SHA,
      appVersion: process.env.npm_package_version,
      build: process.env.BUILD_NUMBER,
      
      // 파일 필터링
      include: [/assets\/.+\.js\.map$/],
      exclude: [/node_modules/],
      
      // CDN 경로 설정
      urlPrefix: '~/static/js',
      
      // 커스텀 경로 변환
      transformPath: (path) => `build/${path}`,
      
      // 업로드 설정
      concurrency: 3,
      retries: 5,
      gzip: true,
      deleteAfterUpload: true,
      
      // CI에서만 실행
      ciOnly: true,
      
      // 추가 헤더
      headers: {
        'X-Custom-Header': 'value',
      },
      
      // 추가 폼 필드
      fields: {
        environment: 'production',
        team: 'frontend',
      },
    }),
  ],
})

설정 옵션

필수 옵션

| 옵션 | 타입 | 설명 | |------|------|------| | endpoint | string | 소스맵을 업로드할 API 엔드포인트 |

선택 옵션

| 옵션 | 타입 | 기본값 | 설명 | |------|------|--------|------| | method | 'POST' \| 'PUT' | 'POST' | HTTP 메서드 | | headers | Record<string, string> | {} | 추가 HTTP 헤더 | | apiKey | string | - | Bearer 토큰 또는 API 키 | | release | string | - | 릴리즈 식별자 (예: git SHA) | | appVersion | string | - | 앱 버전 (semver) | | build | string | - | 빌드 번호 또는 CI 빌드 ID | | fileFieldName | string | 'file' | 파일 업로드용 폼 필드명 | | fields | Record<string, string \| number \| boolean> | {} | 추가 폼 필드 | | include | (string \| RegExp)[] | - | 포함할 파일 패턴 | | exclude | (string \| RegExp)[] | - | 제외할 파일 패턴 | | urlPrefix | string | - | 업로드 파일명에 추가할 접두사 | | transformPath | (path: string) => string | - | 경로 변환 함수 | | concurrency | number | 6 | 동시 업로드 수 | | retries | number | 3 | 재시도 횟수 | | gzip | boolean | true | gzip 압축 사용 여부 | | deleteAfterUpload | boolean | false | 업로드 후 로컬 파일 삭제 | | ciOnly | boolean | false | CI 환경에서만 실행 | | verbose | boolean | CI에서 true, 로컬에서 false | 상세 로그 출력 |

CI 환경 감지

플러그인은 다음 환경 변수를 통해 CI 환경을 자동으로 감지합니다:

• CI
• GITHUB_ACTIONS
• GITLAB_CI
• BUILDKITE
• CIRCLECI
• TRAVIS
• BITBUCKET_BUILD_NUMBER

환경 변수 예시

# .env 파일
SOURCEMAP_API_KEY=your-api-key
GIT_SHA=$(git rev-parse HEAD)
BUILD_NUMBER=$CI_BUILD_NUMBER

사용 예시

sourcemapUpload({
  endpoint: 'https://api.your-service.imqa.io/api/sourcemaps',
  apiKey: process.env.IMQA_AUTH_TOKEN,
  release: process.env.IMQA_SERVICE_NAME,
  urlPrefix: '~/dist/',
  include: [/\.js\.map$/],
  ciOnly: true,
})

GitHub Actions와 함께 사용

# .github/workflows/deploy.yml
- name: Build and upload sourcemaps
  env:
    SOURCEMAP_API_KEY: ${{ secrets.SOURCEMAP_API_KEY }}
    GIT_SHA: ${{ github.sha }}
  run: npm run build

문제 해결

소스맵이 업로드되지 않는 경우

1. build.sourcemap: true가 설정되어 있는지 확인
2. endpoint가 올바른지 확인
3. verbose: true로 설정하여 상세 로그 확인
4. include/exclude 패턴이 올바른지 확인

CI에서만 실행하고 싶은 경우

sourcemapUpload({
  // ... 기타 설정
  ciOnly: true, // 로컬에서는 실행되지 않음
})

특정 파일만 업로드하고 싶은 경우

sourcemapUpload({
  // ... 기타 설정
  include: [/assets\/.+\.js\.map$/], // assets 폴더의 JS 소스맵만
  exclude: [/vendor/, /node_modules/], // vendor, node_modules 제외
})

라이선스

ONYCOM. All right reserved.