@upgoose/vite-plugin

@upgoose/vite-plugin

Upload source maps to Upgoose automatically on build, so error stack traces are symbolicated back to original file, line, column, and function names — no more index-BaRQ9avt.js:1:48211.

Ships two ways to upload:

• a Vite plugin that runs after vite build, and
• a CLI (upgoose-sourcemaps) for CI or non-Vite builds.

Zero runtime dependencies (uses Node 18+ fetch/FormData). Vite is an optional peer dependency — the CLI works without it.

Install

npm install -D @upgoose/vite-plugin

Vite plugin

// vite.config.ts
import { defineConfig } from "vite";
import { upgooseSourceMaps } from "@upgoose/vite-plugin";

export default defineConfig({
  plugins: [upgooseSourceMaps({ dsn: process.env.UPGOOSE_DSN })],
});

That's the whole setup. On vite build the plugin:

1. enables hidden source maps (build.sourcemap: "hidden") if you haven't set it,
2. injects the release into the bundle, so @upgoose/browser's upgoose.init() reports a matching release with no wiring,
3. collects every .map and uploads them in one request tagged with that release, then
4. deletes them from the build output so they never ship to production.

Pair it with the SDK using the same DSN — and never touch release again:

// main.tsx
import upgoose from "@upgoose/browser";
upgoose.init({ dsn: import.meta.env.VITE_UPGOOSE_DSN });

If credentials aren't set, it logs a warning and skips — it never fails your build for missing config.

Options

Option	Default	Description
dsn	UPGOOSE_DSN	https://<API_KEY>@api.upgoose.app/<PROJECT_ID> — supplies apiKey, apiUrl, projectId.
apiKey	DSN → UPGOOSE_API_KEY	Project API key (ug_…).
projectId	DSN → UPGOOSE_PROJECT_ID	Project ID or public numeric ID.
apiUrl	DSN → UPGOOSE_API_URL → https://api.upgoose.app	API base URL.
release	UPGOOSE_RELEASE → git short SHA	Tag maps are stored under; injected into the bundle so the SDK matches it.
sourcemap	true	Auto-enable hidden source maps when unset. false = manage build.sourcemap yourself.
outDir	Vite's build.outDir	Directory scanned for .map files.
clean	false	DELETE existing maps for this release before uploading.
deleteAfterUpload	true	Remove .map files from the build output after upload.
failOnError	false	Throw (fail the build) on upload error instead of warning.
silent	false	Suppress [upgoose] logs.
disable	false	Skip the plugin entirely (e.g. gate on an env flag).

CLI

For CI pipelines or bundlers other than Vite:

upgoose-sourcemaps \
  --dir dist \
  --release "$(git rev-parse --short HEAD)" \
  --project-id "$UPGOOSE_PROJECT_ID" \
  --api-key "$UPGOOSE_API_KEY"

Flags fall back to the same env vars as the plugin. Run upgoose-sourcemaps --help for the full list. Unlike the plugin, the CLI keeps .map files on disk by default — pass --delete-after (or rm them yourself before deploying).

Matching the release

Symbolication looks maps up by release, so the SDK must report the same release the maps were uploaded under. With @upgoose/browser ≥0.3 this is automatic — the plugin resolves the release once (UPGOOSE_RELEASE, else the short git SHA) and injects it into the bundle, so upgoose.init() picks it up with nothing to wire. Just don't pass release to init().

If you pin the release explicitly, set the same value in both places:

// vite.config.ts
upgooseSourceMaps({ dsn: process.env.UPGOOSE_DSN, release: process.env.BUILD_SHA });
// app entry
upgoose.init({ dsn: import.meta.env.VITE_UPGOOSE_DSN, release: import.meta.env.VITE_BUILD_SHA });

If the two don't match, the worker won't find the maps and traces stay minified.

The injected-release feature needs @upgoose/browser ≥0.3 and @upgoose/vite-plugin ≥0.2. With an older SDK, pass release to init() yourself; the upload still works.

License

BSD-3-Clause