@proliferate_ai/build-plugins

Build plugins for automatic release ID injection. Supports Webpack, Vite, Rollup, and esbuild.

Why This Package?

The Proliferate SDK needs a release ID to match errors with source maps. This package automatically:

1. Extracts the git SHA (or uses a custom release ID)
2. Injects __PROLIFERATE_RELEASE__ as a global constant
3. Makes it available to the SDK at runtime

Without this, your stack traces will remain minified and unreadable.

Installation

npm install @proliferate_ai/build-plugins --save-dev
# or
yarn add @proliferate_ai/build-plugins --dev
# or
pnpm add @proliferate_ai/build-plugins --save-dev

Usage

Vite

// vite.config.js
import { proliferateVite } from '@proliferate_ai/build-plugins/vite';

export default {
  plugins: [
    proliferateVite(), // Auto-detects git SHA
  ],
};

Webpack

// webpack.config.js
const { ProliferateWebpackPlugin } = require('@proliferate_ai/build-plugins/webpack');

module.exports = {
  plugins: [
    new ProliferateWebpackPlugin(), // Auto-detects git SHA
  ],
};

Rollup

// rollup.config.js
import { proliferateRollup } from '@proliferate_ai/build-plugins/rollup';

export default {
  plugins: [
    proliferateRollup(), // Auto-detects git SHA
  ],
};

esbuild

// build.js
import { proliferateEsbuild } from '@proliferate_ai/build-plugins/esbuild';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  plugins: [proliferateEsbuild()],
});

Or use the define helper directly:

import { getEsbuildDefine } from '@proliferate_ai/build-plugins/esbuild';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  define: getEsbuildDefine(),
});

Configuration

All plugins accept the same options:

interface ReleaseOptions {
  /** Custom release ID. If not provided, uses git SHA. */
  release?: string;

  /** Git ref to use (default: "HEAD"). */
  gitRef?: string;

  /** Use short SHA (default: true). */
  shortSha?: boolean;

  /** Fallback if git is unavailable. */
  fallback?: string;

  /** Log the release ID during build (default: true). */
  verbose?: boolean;
}

Examples

Custom release ID:

proliferateVite({ release: 'v1.2.3' });

Use full SHA:

proliferateVite({ shortSha: false });

Custom git ref:

proliferateVite({ gitRef: 'main' });

Fallback for non-git environments:

proliferateVite({ fallback: process.env.BUILD_ID });

Disable logging:

proliferateVite({ verbose: false });

Release ID Resolution

The plugins resolve the release ID in this order:

1. Explicit release option - Use if you want full control
2. PROLIFERATE_RELEASE environment variable - Useful in CI/CD
3. Git SHA - Extracted via git rev-parse
4. fallback option - Fallback value if git is unavailable
5. "unknown" - Last resort (source maps won't work)

CI/CD Integration

Set the PROLIFERATE_RELEASE environment variable in your CI pipeline:

GitHub Actions:

env:
  PROLIFERATE_RELEASE: ${{ github.sha }}

GitLab CI:

variables:
  PROLIFERATE_RELEASE: $CI_COMMIT_SHA

How It Works

1. During build, the plugin resolves the release ID
2. It injects __PROLIFERATE_RELEASE__ as a global constant
3. The SDK reads this constant at runtime
4. Every error payload includes the release ID
5. Backend matches the release ID to uploaded source maps

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│   Your Build    │     │   Proliferate    │     │   Proliferate       │
│   (webpack/etc) │     │   SDK            │     │   Backend           │
└────────┬────────┘     └────────┬─────────┘     └──────────┬──────────┘
         │                       │                          │
         │  1. Plugin injects    │                          │
         │     release ID        │                          │
         ├──────────────────────►│                          │
         │                       │                          │
         │                       │  2. Error includes       │
         │                       │     release: "a1b2c3d"   │
         │                       ├─────────────────────────►│
         │                       │                          │
         │                       │                          │  3. Match to
         │                       │                          │     source maps

Troubleshooting

"No release ID configured"

The SDK couldn't find a release ID. Check:

1. Is the build plugin installed and configured?
2. Is git available in your build environment?
3. Is the PROLIFERATE_RELEASE env var set in CI?

Git not found

In Docker or CI environments, git might not be available:

// Use environment variable fallback
proliferateVite({
  fallback: process.env.BUILD_ID || process.env.CI_COMMIT_SHA,
});

Source maps not resolving

Ensure the release ID used during build matches the one used when uploading source maps:

# Build with the plugin (auto-detects SHA)
npm run build

# Upload with the same SHA
proliferate sourcemaps upload \
  --release $(git rev-parse --short HEAD) \
  --path ./dist

Core API

For advanced usage, you can use the core functions directly:

import { getReleaseId, createDefineConfig } from '@proliferate_ai/build-plugins';

// Get release info
const { id, source } = getReleaseId({ shortSha: true });
console.log(`Release: ${id} (from ${source})`);

// Get define config for any build tool
const config = createDefineConfig();
// { '__PROLIFERATE_RELEASE__': '"a1b2c3d"' }

License

MIT