Releases - Proliferate

Overview

Releases in Proliferate represent specific versions of your application. They’re primarily used to associate source maps with error events, enabling you to see original source code in stack traces even when your production code is minified or transpiled.

What is a Release?

A release is a versioned deployment of your application. Each release can have:

Version identifier: Typically a git commit SHA, semantic version, or build number
Source maps: Files that map minified code back to original source
URL prefix: The base URL pattern for matching error stack traces

The Release Workflow

Source map upload follows a three-step workflow:

Create Release

Create a new release with a version identifier (usually automated by your build tool)

Upload Source Maps

Upload all source map files for this release

Finalize Release

Mark the release as complete and ready for use

Build plugins (Next.js, Webpack, Vite) handle this workflow automatically. Manual uploads are only needed for custom build processes.

Creating a Release

Automatic (Build Plugins)

The recommended approach is using build plugins that automatically create releases during your build process:

next.config.js

const { withProliferate } = require('@proliferate/nextjs');

module.exports = withProliferate({
  // Your Next.js config...
}, {
  apiKey: process.env.PROLIFERATE_API_KEY,
  autoUploadSourcemaps: true,
  // Release version auto-detected from git or VERCEL_GIT_COMMIT_SHA
});

Manual (API)

Create a release manually using the API:

curl -X POST https://api.proliferate.com/api/v1/releases \
  -H "Authorization: Bearer pk_YOUR_API_KEY" \
  -F "version=v1.2.3" \
  -F "url_prefix=~/"

Request Parameters:

version

string

required

Version identifier (git SHA, semver, build number). Max 128 characters.

url_prefix

string

default:"~/"

URL prefix for matching stack trace URLs. Use ~/ for root-relative paths.

Response:

{
  "id": 42,
  "project_id": 123,
  "version": "v1.2.3",
  "url_prefix": "~/",
  "created_at": "2025-01-15T10:30:00Z",
  "finalized_at": null,
  "source_map_count": 0
}

Uploading Source Maps

After creating a release, upload your source map files:

curl -X POST https://api.proliferate.com/api/v1/sourcemaps \
  -H "Authorization: Bearer pk_YOUR_API_KEY" \
  -F "release=v1.2.3" \
  -F "url=~/static/js/main.abc123.js" \
  -F "sourcemap=@dist/static/js/main.abc123.js.map"

Request Parameters:

release

string

required

Release version to associate this source map with

url

string

required

The URL of the JavaScript file (as it appears in stack traces)

sourcemap

file

required

The .map file

url_prefix

string

default:"~/"

URL prefix (should match the release’s url_prefix)

Upload one source map file per JavaScript bundle. For a typical React app, this might be 3-5 files (main bundle, vendor chunks, etc.).

Finalizing a Release

After all source maps are uploaded, finalize the release to mark it as complete:

curl -X POST https://api.proliferate.com/api/v1/releases/v1.2.3/finalize \
  -H "Authorization: Bearer pk_YOUR_API_KEY"

Finalizing a release is optional but recommended. It signals that the release is complete and helps with debugging if source maps are missing.

Viewing Releases

List all releases for a project in the dashboard or via API:

GET /api/v1/projects/{project_id}/releases?limit=50&offset=0

Response:

{
  "releases": [
    {
      "id": 42,
      "project_id": 123,
      "version": "v1.2.3",
      "url_prefix": "~/",
      "created_at": "2025-01-15T10:30:00Z",
      "finalized_at": "2025-01-15T10:35:00Z",
      "source_map_count": 5
    }
  ],
  "total": 1
}

Get a Specific Release

GET /api/v1/projects/{project_id}/releases/{version}

List Source Maps for a Release

GET /api/v1/projects/{project_id}/releases/{version}/sourcemaps

Response:

{
  "source_maps": [
    {
      "id": 101,
      "release_id": 42,
      "url": "~/static/js/main.abc123.js",
      "content_hash": "sha256:abc...",
      "file_size": 524288,
      "created_at": "2025-01-15T10:32:00Z"
    }
  ],
  "total": 1
}

Version Naming Strategies

Git Commit SHA (Recommended)

Use the full git commit SHA as your release version:

version=$(git rev-parse HEAD)

Pros:

Unique per deployment
Easy to correlate errors with code
Works with GitHub source linking

Cons:

Not human-readable

Semantic Versioning

Use semver for user-facing releases:

version="v1.2.3"

Pros:

Human-readable
Matches release tags

Cons:

Need to update manually
May have multiple deployments per version

Build Number

Use CI/CD build numbers:

version="build-${CI_BUILD_NUMBER}"

Pros:

Auto-incremented
Unique per build

Cons:

No direct code correlation

Hybrid Approach

Combine approaches for the best of both worlds:

version="v1.2.3-${git_sha:0:8}"

Example: v1.2.3-a1b2c3d4

How Source Maps Work

When an error occurs in production:

SDK Captures Error

The SDK captures the minified stack trace and sends it with the release field set

Backend Matches Release

Proliferate finds the release matching the error’s version

Maps Stack Frames

Each stack frame’s URL, line, and column are mapped using the corresponding source map

Displays Original Code

The dashboard shows the original source code with proper file names, line numbers, and function names

URL Prefix Patterns

The url_prefix helps match stack trace URLs to your source maps.

Root-Relative (`~/`)

For URLs like https://example.com/static/js/main.js:

url_prefix: "~/"
url: "~/static/js/main.js"

Stack trace URL https://example.com/static/js/main.js matches.

Absolute URL

For CDN-hosted assets:

url_prefix: "https://cdn.example.com/"
url: "https://cdn.example.com/v123/app.js"

Multiple Prefixes

If you serve assets from multiple domains, create separate releases or upload source maps with different URL patterns.

Deleting Releases

Remove old releases to save storage:

DELETE /api/v1/projects/{project_id}/releases/{version}

Deleting a release removes all associated source maps. Errors with this release version will no longer have resolved stack traces.

Best Practices

Automatic Uploads in CI/CD

Always upload source maps as part of your deployment pipeline:

.github/workflows/deploy.yml

- name: Build and upload source maps
  env:
    PROLIFERATE_API_KEY: ${{ secrets.PROLIFERATE_API_KEY }}
  run: |
    npm run build
    # Source maps auto-uploaded by build plugin

Version from Environment

Use environment variables in CI:

const release =
  process.env.VERCEL_GIT_COMMIT_SHA ||  // Vercel
  process.env.GITHUB_SHA ||              // GitHub Actions
  process.env.CI_COMMIT_SHA ||           // GitLab CI
  process.env.HEROKU_SLUG_COMMIT;        // Heroku

Clean Up Old Releases

Periodically delete releases older than your retention policy (e.g., 90 days) to save storage.

Test Source Maps Locally

Before deploying, verify source maps work:

npm run build
npx source-map-cli dist/main.js.map 1 100

Don’t Upload Source Maps to Production

Keep .map files out of your production bundle:

webpack.config.js

{
  devtool: 'hidden-source-map', // Generates maps but doesn't link them
}

This keeps your source code private while still allowing Proliferate to resolve stack traces.

Platform

​Overview

​What is a Release?

​The Release Workflow

​Creating a Release

​Automatic (Build Plugins)

​Manual (API)

​Uploading Source Maps

​Finalizing a Release

​Viewing Releases

​Get a Specific Release

​List Source Maps for a Release

​Version Naming Strategies

​Git Commit SHA (Recommended)

​Semantic Versioning

​Build Number

​Hybrid Approach

​How Source Maps Work

​URL Prefix Patterns

​Root-Relative (~/)

​Absolute URL

​Multiple Prefixes

​Deleting Releases

​Best Practices

​Automatic Uploads in CI/CD

​Version from Environment

​Clean Up Old Releases

​Test Source Maps Locally

​Don’t Upload Source Maps to Production

Overview

What is a Release?

The Release Workflow

Creating a Release

Automatic (Build Plugins)

Manual (API)

Uploading Source Maps

Finalizing a Release

Viewing Releases

Get a Specific Release

List Source Maps for a Release

Version Naming Strategies

Git Commit SHA (Recommended)

Semantic Versioning

Build Number

Hybrid Approach

How Source Maps Work

URL Prefix Patterns

Root-Relative (`~/`)

Absolute URL

Multiple Prefixes

Deleting Releases

Best Practices

Automatic Uploads in CI/CD

Version from Environment

Clean Up Old Releases

Test Source Maps Locally

Don’t Upload Source Maps to Production