npm package: @interfere/vite
Description: Vite build plugin and client initialization for Interfere.
Author: Interfere
Latest version: 0.1.0

<p align="center">
  <a href="https://interfere.com">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://qyzkf4cgb8ydxtq1.public.blob.vercel-storage.com/v2/header/logo-dark.png">
      <img src="https://qyzkf4cgb8ydxtq1.public.blob.vercel-storage.com/v2/header/logo-light.png" height="64">
    </picture>
  </a>
  <h1 align="center">@interfere/vite</h1>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@interfere/vite"><img src="https://img.shields.io/npm/v/@interfere/vite.svg" /></a>
  <a href="https://github.com/interfere-inc/interfere/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@interfere/vite.svg" /></a>
  <a href="https://www.npmjs.com/package/@interfere/vite"><img src="https://img.shields.io/npm/dm/@interfere/vite.svg" /></a>
</p>

<p align="center">
  Vite build plugin and client initialization for <a href="https://interfere.com">Interfere</a> — error tracking, session replay, and analytics for modern product teams.
</p>

<p align="center">
  <a href="https://support.interfere.com/docs">Documentation</a>
  ·
  <a href="https://support.interfere.com/roadmap">Feature Requests</a>
  ·
  <a href="https://support.interfere.com/requests">Report a Bug</a>
  ·
  <a href="mailto:support@interfere.com">Get Help</a>
</p>

---

## Getting Started

### Prerequisites

- Vite `>=5`
- React `>=19`
- [`@interfere/react`](https://www.npmjs.com/package/@interfere/react) for the React provider and hooks

### Installation

```bash
npm install @interfere/vite @interfere/react
```

### Quick Start

**1. Add the Vite plugin**

```ts
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { interfere } from "@interfere/vite/plugin";

export default defineConfig({
  plugins: [react(), interfere()],
});
```

The plugin automatically injects your build ID and release ID into the page at build time. By default the build ID is resolved from `git rev-parse HEAD`; you can override it via plugin options or the `VITE_INTERFERE_BUILD_ID` environment variable.

**2. Initialize the client**

```ts
// src/main.tsx
import { init } from "@interfere/vite/init";

init();
```

Call `init()` before mounting your React tree so the SDK is ready to capture errors from first render.

**3. Add the React provider**

```tsx
// src/App.tsx
import { InterfereProvider } from "@interfere/react/provider";

function App() {
  return (
    <InterfereProvider>
      <YourApp />
    </InterfereProvider>
  );
}
```

### Environment Variables

| Variable | Required | Description |
| --- | --- | --- |
| `VITE_INTERFERE_PUBLIC_KEY` | Yes | Your project public key (injected into the page by the plugin) |
| `VITE_INTERFERE_BUILD_ID` | No | Override the auto-detected build ID |

## Plugin Options

```ts
interfere({
  buildId: "custom-build-id",
  releaseId: "v1.2.3",
});
```

| Option | Default | Description |
| --- | --- | --- |
| `buildId` | `VITE_INTERFERE_BUILD_ID` → Git SHA → random UUID | Unique identifier for this build |
| `releaseId` | Same as `buildId` | Semantic release identifier for grouping errors by deploy |

## Identity Management

Link sessions to your authenticated users with `identity.set()`:

```tsx
import { useInterfere } from "@interfere/react/provider";

function useInterfereIdentity() {
  const { identity } = useInterfere();

  // Clerk, Auth0, etc.
  const { user } = useAuthProvider();

  useEffect(() => {
    if (user) {
      identity.set({
        identifier: user.id,
        name: user.name,
        email: user.email,
        source: { type: "clerk", name: "Clerk" },
      });
    } else {
      identity.clear();
    }
  }, [user]);

  return null;
}
```

### Parameters

| Field | Required | Description |
| --- | --- | --- |
| `identifier` | Yes | Unique user ID (your internal ID, not email) |
| `source` | Yes | Auth source: `{ type: "clerk", name: "Clerk" }`, `{ type: "auth0", name: "Auth0" }`, or `{ type: "custom", name: "Your Provider" }` |
| `name` | No | Display name |
| `email` | No | Email address |
| `avatar` | No | Avatar URL |
| `traits` | No | Arbitrary key-value metadata (`Record<string, unknown>`) |

### API

| Method | Description |
| --- | --- |
| `identity.set(params)` | Link the current session to a user. Deduplicated per session — only the first call sends a request. |
| `identity.get()` | Returns the current `IdentifyParams`, or `null` if no identity has been set. |

Identity is automatically cleared when the SDK is closed or the session rotates.

## Consent Management

By default, all SDK features are active. To gate features behind user consent, pass a `consent` prop to the provider:

```tsx
import { InterfereProvider } from "@interfere/react/provider";

function App() {
  return (
    <InterfereProvider consent={{ analytics: true, replay: false }}>
      <YourApp />
    </InterfereProvider>
  );
}
```

### Consent categories

| Category | Plugins | Gated? |
| --- | --- | --- |
| `necessary` | Error tracking | Always on |
| `analytics` | Page events, rage clicks, fingerprint | Yes |
| `replay` | Session replay | Yes |

Omitting the `consent` prop disables gating entirely (all features load). Passing it enables gating — only `necessary` plugins plus explicitly consented categories will activate.

### Imperative API

Use `consent.set()` and `consent.get()` from the `useInterfere` hook:

```tsx
const { consent } = useInterfere();

consent.set({ analytics: true, replay: true }); // selective
consent.set();                                   // grant all
consent.get();                                   // current state, or null if no gating
```

### Initial consent via init

To set consent before React renders (avoiding any window where non-consented plugins might load), pass it to `init()`:

```ts
import { init } from "@interfere/vite/init";

init({ consent: { analytics: false, replay: false } });
```

The provider's `consent` prop will then keep it in sync as the user updates their preferences.

## What's Included

- **Build metadata injection** — automatically tags each build with a Git SHA-derived build and release ID
- **Error tracking** — automatic capture of uncaught errors and unhandled rejections
- **Session replay** — full visual playback of user sessions
- **Page analytics** — SPA-aware pageviews and UI interaction events
- **Rage click detection** — surface frustrated user behavior
- **Consent gating** — fine-grained control over which features activate

## License

MIT