> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinrefine.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins Overview

> Extend SDK functionality with built-in and custom plugins

## Overview

Plugins extend the Refine SDK with additional functionality. The SDK includes three built-in plugins:

| Plugin                                            | Purpose                            |
| ------------------------------------------------- | ---------------------------------- |
| [DebugPlugin](/sdk/plugins/debug-plugin)          | Development logging and validation |
| [ConsentPlugin](/sdk/plugins/consent-plugin)      | GDPR-compliant consent management  |
| [AutoTrackPlugin](/sdk/plugins/auto-track-plugin) | Automatic event tracking           |

## Using Plugins

Register plugins with `refine.use()`:

```typescript theme={null}
import { Refine, DebugPlugin, ConsentPlugin, AutoTrackPlugin } from '@refine-ai/sdk';

const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789'
});

// Add plugins
refine.use(new DebugPlugin({ logEvents: true }));
refine.use(new ConsentPlugin({ required: true }));
refine.use(new AutoTrackPlugin({ pageViews: true }));
```

## Plugin Order

Plugins execute in registration order. For most cases, the recommended order is:

```typescript theme={null}
// 1. Debug first (logs everything)
refine.use(new DebugPlugin({ logEvents: true }));

// 2. Consent second (gates all tracking)
refine.use(new ConsentPlugin({ required: true }));

// 3. AutoTrack last (depends on consent)
refine.use(new AutoTrackPlugin({ pageViews: true }));
```

## Quick Reference

### DebugPlugin

Log events and validate parameters during development:

```typescript theme={null}
import { DebugPlugin } from '@refine-ai/sdk';

refine.use(new DebugPlugin({
  logEvents: true,      // Log all events to console
  validateEvents: true, // Warn about invalid events
  dryRun: false         // If true, don't send events
}));
```

### ConsentPlugin

Gate tracking behind user consent:

```typescript theme={null}
import { ConsentPlugin } from '@refine-ai/sdk';

const consentPlugin = new ConsentPlugin({
  required: true,
  onConsentRequired: () => {
    showConsentBanner();
  }
});

refine.use(consentPlugin);

// When user grants consent
consentPlugin.grant();

// When user denies consent
consentPlugin.deny();
```

### AutoTrackPlugin

Automatically track common events:

```typescript theme={null}
import { AutoTrackPlugin } from '@refine-ai/sdk';

refine.use(new AutoTrackPlugin({
  pageViews: true,
  clicks: {
    selector: '[data-refine-item]',
    extractItemId: (el) => el.dataset.refineItem
  },
  viewability: {
    enabled: true,
    threshold: 0.5,
    duration: 1000
  }
}));
```

## Combining Plugins

Typical production setup:

```typescript theme={null}
import { 
  Refine, 
  DebugPlugin, 
  ConsentPlugin, 
  AutoTrackPlugin 
} from '@refine-ai/sdk';

const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789',
  privacy: {
    requireConsent: true
  }
});

// Development: enable debug logging
if (process.env.NODE_ENV === 'development') {
  refine.use(new DebugPlugin({
    logEvents: true,
    validateEvents: true
  }));
}

// Production: consent management
const consentPlugin = new ConsentPlugin({
  required: true,
  onConsentRequired: () => {
    document.getElementById('consent-banner')?.classList.remove('hidden');
  }
});
refine.use(consentPlugin);

// Auto-tracking with consent gate
refine.use(new AutoTrackPlugin({
  pageViews: true,
  viewability: { enabled: true, threshold: 0.5, duration: 1000 }
}));

// Consent UI handlers
document.getElementById('accept-cookies')?.addEventListener('click', () => {
  consentPlugin.grant();
  document.getElementById('consent-banner')?.classList.add('hidden');
});

document.getElementById('decline-cookies')?.addEventListener('click', () => {
  consentPlugin.deny();
  document.getElementById('consent-banner')?.classList.add('hidden');
});
```

## Next Steps

<CardGroup cols={3}>
  <Card title="Debug Plugin" icon="bug" href="/sdk/plugins/debug-plugin">
    Development tools
  </Card>

  <Card title="Consent Plugin" icon="shield-check" href="/sdk/plugins/consent-plugin">
    Privacy compliance
  </Card>

  <Card title="Auto Track Plugin" icon="wand-magic-sparkles" href="/sdk/plugins/auto-track-plugin">
    Automatic tracking
  </Card>
</CardGroup>