@sophonz/vite-sourcemap

한국어

Vite plugin for uploading source maps to error tracking services.

Automatically discovers and uploads .map files from your build output with support for gzip compression, optional deletion, concurrent uploads, and filter patterns.

Part of the Sophonz OpenTelemetry suite.

Install

bun add -D @sophonz/vite-sourcemap
# or
pnpm add -D @sophonz/vite-sourcemap
# or
npm install --save-dev @sophonz/vite-sourcemap

Usage

Add to vite.config.ts:

import { defineConfig } from 'vite';
import sourcemapUpload from '@sophonz/vite-sourcemap';

export default defineConfig({
  build: {
    sourcemap: true
  },
  plugins: [
    sourcemapUpload({
      endpoint: process.env.SOURCEMAP_ENDPOINT,
      apiKey: process.env.SOURCEMAP_API_KEY,
      release: process.env.GIT_SHA,
      appVersion: process.env.npm_package_version,
      urlPrefix: '~/assets/js',
      ciOnly: true,
      deleteAfterUpload: true
    })
  ]
});

Plugin Options

SourcemapUploadPluginOptions is the exported options type.

| Option | Type | Default | Description | |--------|------|---------|-------------| | endpoint | string | required | Destination URL for sourcemap uploads | | apiKey | string | - | Bearer token (sets Authorization header) | | method | 'POST' | 'PUT' | 'POST' | HTTP method for upload requests | | headers | object | {} | Additional HTTP headers | | release | string | - | Release identifier (sent as form field) | | appVersion | string | - | Semantic version (sent as form field) | | build | string | - | Build/commit SHA (sent as form field) | | fileFieldName | string | 'file' | Form field name for file upload | | fields | object | - | Additional form fields per upload | | include | (string | RegExp)[] | - | Patterns to match (all if not set) | | exclude | (string | RegExp)[] | - | Patterns to skip | | urlPrefix | string | - | Prefix added to uploaded filename | | transformPath | function | - | Custom path transformation | | concurrency | number | 6 | Parallel uploads | | retries | number | 3 | Attempts per file | | gzip | boolean | true | Compress with gzip before upload | | deleteAfterUpload | boolean | false | Remove .map files after success | | ciOnly | boolean | false | Skip upload in local development | | verbose | boolean | auto | Log details (auto: true in CI) | | appType | AppType | - | Target platform: 'ANDROID', 'IOS', 'WEB', 'ALL' or null |

Behavior

• Runs during Vite build in post phase (after assets written)
• Discovers .map files from both bundle manifest and filesystem scan
• Filters by include/exclude regexes against output-relative paths
• Uploads with configurable concurrency (default: 6 concurrent)
• Retries failed uploads with exponential backoff
• Optionally gzips sourcemaps (30-50% size reduction typical)
• Fails build if any uploads fail (can catch with try/catch)

Peer Dependencies

• vite@^5.0.0 || ^6.0.0

License

See LICENSE in this package.

Part of sophonz-js.