@guidelytech/sourcemaps

Uploads your build's JavaScript source maps to Guidely so exceptions on the Errors page show your original files, functions and lines instead of minified code. Zero runtime dependencies; Node ≥ 18.

npx @guidelytech/sourcemaps upload --dir dist --release "$GIT_SHA" --delete-after

1. Create a secret API key with the sourcemaps:write scope in Guidely (Settings → API keys) and store it as a CI secret GUIDELY_SOURCEMAP_KEY. Never ship it to the browser.
2. Build with source maps enabled.
3. Upload them with the same release the SDK reports, then deploy (without the .map files).
4. Set the same value as the SDK's release option: createGuidely({ …, release }), NEXT_PUBLIC_GUIDELY_RELEASE, VITE_GUIDELY_RELEASE / PUBLIC_GUIDELY_RELEASE, or <script data-release="…"> for the script tag. Exceptions are matched to maps by release + script URL path.

Commands

guidely-sourcemaps upload --dir <dir> [--url-prefix /] [--release <r>] [--api-url <url>] [--key <key>]
                          [--include .js.map] [--delete-after] [--dry-run]
guidely-sourcemaps verify [--key <key>] [--api-url <url>]

| Option | Env | Default | | |---|---|---|---| | --dir | — | (required) | Build output searched recursively for *.js.map files whose minified file (same name without .map) sits next to them. | | --url-prefix | — | / | URL path the directory is served under. The minified file's URL path is url-prefix + its path relative to --dir. | | --release | GUIDELY_RELEASE | — | App version / commit SHA (≤ 100 chars). | | --api-url | GUIDELY_API_URL | https://api.guidely.app | Your Guidely API. | | --key | GUIDELY_SOURCEMAP_KEY | — | Secret key with sourcemaps:write. Never printed. | | --include | — | .js.map | File-name suffix of the maps to upload. | | --delete-after | — | off | Delete each local .map once it uploaded successfully (otherwise deploying the build publishes your original source). | | --dry-run | — | off | List what would be uploaded; no key needed. |

Maps must be JSON with version: 3 (others are skipped with a warning) and ≤ 25 MB. Uploads are batched (≤ 50 files / 40 MB per request) and retried 3× on network errors, 5xx and 429. The command prints one line per map and a summary, and exits with code 1 if any map failed, the key was rejected (401/403: invalid or revoked key, or missing sourcemaps:write scope) or no maps were found.

verify calls GET /api/v1/sourcemaps/whoami and prints the project and key prefix.

Frameworks

| Build | Enable maps | Upload | |---|---|---| | Vite (React, Vue, SvelteKit client) | build: { sourcemap: true } ("hidden" keeps the //# sourceMappingURL comment out of the files) | --dir dist --url-prefix / (SvelteKit: --dir .svelte-kit/output/client --url-prefix /) | | Next.js | productionBrowserSourceMaps: true in next.config.js | --dir .next/static --url-prefix /_next/static/ | | Served from a CDN path | — | --url-prefix /assets/ (or the full URL, e.g. https://cdn.example.com/app/, matching the script URLs in stack traces) |

GitHub Actions

- run: pnpm build
  env:
    VITE_GUIDELY_RELEASE: ${{ github.sha }}   # same release the SDK reports
- run: npx @guidelytech/sourcemaps upload --dir dist --release ${{ github.sha }} --delete-after
  env:
    GUIDELY_SOURCEMAP_KEY: ${{ secrets.GUIDELY_SOURCEMAP_KEY }}
    GUIDELY_API_URL: https://guidely.example.com
- run: ./deploy.sh   # deploys dist without the .map files

Next.js:

- run: pnpm next build
  env:
    NEXT_PUBLIC_GUIDELY_RELEASE: ${{ github.sha }}
- run: npx @guidelytech/sourcemaps upload --dir .next/static --url-prefix /_next/static/ --release ${{ github.sha }} --delete-after
  env:
    GUIDELY_SOURCEMAP_KEY: ${{ secrets.GUIDELY_SOURCEMAP_KEY }}

Programmatic use

import { uploadSourceMaps } from "@guidelytech/sourcemaps";

const result = await uploadSourceMaps({ dir: "dist", urlPrefix: "/", release: process.env.GIT_SHA, key: process.env.GUIDELY_SOURCEMAP_KEY, deleteAfter: true });
// { release, files, uploaded: [{ path, sizeBytes, sources, hasContent, replaced }], errors: [{ path, message }], skipped, deleted, dryRun }

Also exported: findSourceMaps, urlPathFor, batchFiles, verifyKey, runCli, GuidelyAuthError.