@fixback/vite-plugin

Upload your production build's sourcemaps to Fixback automatically, as part of vite build. The Issues Fixback captures on your site then arrive with a symbolicated code-area pointer — the original file:line (with source context) where the error likely lives, not a minified frame.

It's the zero-CI-step companion to @fixback/cli: the same upload, without a separate npx fixback sourcemaps upload step in your pipeline.

npm install -D @fixback/vite-plugin

// vite.config.ts
import { defineConfig } from "vite";
import { fixbackSourcemaps } from "@fixback/vite-plugin";

export default defineConfig({
  plugins: [fixbackSourcemaps()],
});

That's the whole integration — there is no release to keep in sync. The plugin resolves the build's Release, uploads the maps under it, and injects it into the bundle, so the SDK stamps captured errors with the very same value:

Fixback.init({ key: "pk_…" }); // the release comes from the build

If a build has no secret key in its environment, the plugin logs a warning and does nothing — your build still succeeds.

What it does

On vite build (never during dev), after the bundle is written, the plugin:

1. Ensures sourcemaps exist. If you haven't set build.sourcemap, it turns it on as 'hidden' — maps are emitted but not referenced by your JS, so nothing leaks to visitors. An explicit build.sourcemap is always respected.
2. Uploads every *.js.map to Fixback, keyed by release and ~/-abstract path, authenticated with your Project secret key.
3. Prunes the uploaded maps from the build output so they aren't deployed (skipped when you opted into referenced sourcemap: true maps — see below).

The SSR pass of an SSR build is skipped; only the client build's maps upload.

Release

The release identifies the build these maps belong to. Resolved as:

release option → FIXBACK_RELEASE → your CI provider's commit SHA (GitHub Actions, Vercel, Cloudflare Pages, Netlify) → the current git commit SHA.

Builders who name versions can (release: pkg.version); everyone else gets the commit SHA for free — including in Docker builds and CI images that check out without a .git directory, which is why the CI variables sit ahead of the git fallback.

You do not repeat it in the SDK. The plugin defines the resolved value into your bundle as __FIXBACK_RELEASE__, and the SDK reads it whenever init() gets no explicit release. The uploaded maps and the captured errors therefore carry one value, not two that have to be kept equal — which matters because the default is a git SHA, and a git SHA cannot be typed into source.

An explicit release in init() still wins, as does a define you write for __FIXBACK_RELEASE__ yourself. Set injectRelease: false to opt out.

One limit: injection reaches SDK code your bundler processes, so an npm install is covered and a <script>-tag UMD build is not — that one has already been built by the time Vite runs. There, either pass release to init(), or set globalThis.__FIXBACK_RELEASE__ before calling it.

Auth

Uploads authenticate with your Project's secret key (Project settings → API keys), read from FIXBACK_SECRET_KEY or the secretKey option. It's the server-side credential your CI already holds — never ship it in the page (that's the publishable pk_… key's job), and prefer the environment variable over inlining it in a committed config.

Options

All optional — fixbackSourcemaps() works with just FIXBACK_SECRET_KEY set.

| Option | Default | | |---|---|---| | release | $FIXBACK_RELEASE, else a CI commit SHA, else git HEAD SHA | Build identifier (1–100 visible chars, no spaces/slashes) | | injectRelease | true | Define the resolved release into the bundle as __FIXBACK_RELEASE__, so the SDK needs no release option | | secretKey | $FIXBACK_SECRET_KEY | Project secret key (sk_…) | | apiUrl | $FIXBACK_API_URL, else the hosted API | Self-hosted deployments point here | | urlPrefix | ~/ | Where bundles are served relative to the site root, e.g. ~/static | | deleteAfterUpload | delete unless sourcemap: true | Remove uploaded .map files after upload so they aren't served | | ensureSourcemaps | true | When build.sourcemap is unset, turn on 'hidden' maps | | strict | false | Fail the build on an upload problem (default: warn and continue) | | disable | false | Turn the plugin off entirely (e.g. gate on an env var) | | silent | false | Silence the informational log lines |

Notes

• Failures never break your deploy. A missing key, an unreachable API, or a failed upload is a warning by default — set strict: true to make CI fail loudly instead.
• Referenced vs. hidden maps. With the default 'hidden' maps, .map files aren't referenced by your JS, so pruning them after upload is clean. If you set build.sourcemap: true, the maps are referenced and would be served publicly; the plugin keeps them (to avoid a dangling sourceMappingURL) and warns. Prefer 'hidden' to keep sourcemaps private — Fixback reads them from disk either way.
• Re-running is safe. Artifacts upsert per (release, path); a re-deploy of the same release doesn't duplicate.
• Prefer the CLI (@fixback/cli) when your build isn't Vite, or when you want the upload decoupled from the build (a separate CI step).

See ADR-0024 for why analysis is sourcemaps-only, and ADR-0030 for why this plugin reuses the CLI's upload core.