npm package: @proliferate_ai/build-plugins
Description: Build plugins for Proliferate SDK release ID injection
Author: Proliferate
Latest version: 1.0.1

# @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

```bash
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

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

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

### Webpack

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

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

### Rollup

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

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

### esbuild

```javascript
// 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:

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

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

## Configuration

All plugins accept the same options:

```typescript
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:**

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

**Use full SHA:**

```javascript
proliferateVite({ shortSha: false });
```

**Custom git ref:**

```javascript
proliferateVite({ gitRef: 'main' });
```

**Fallback for non-git environments:**

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

**Disable logging:**

```javascript
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:**

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

**GitLab CI:**

```yaml
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:

```javascript
// 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:

```bash
# 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:

```typescript
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