# Errly SDK – AI Implementation Guide
> Packages: @gonzitech/errly-browser · @gonzitech/errly-node · @gonzitech/errly-nextjs · @gonzitech/errly-replay
> Full reference: https://errly.app/llms.txt

---QUICK START---
Paste this section into your AI assistant. It contains everything needed for a standard Errly integration.

## What is Errly?
Errly is an EU-hosted error tracking service (GDPR-compliant). SDKs capture exceptions and send
them to ingest.errly.app. Get your DSN from: Errly Dashboard → Project Settings → Client Keys.

## DSN Format
https://<clientKey>@ingest.errly.app/<projectId>
Replace <clientKey> and <projectId> with the values from your dashboard.

## Install

Browser:
  pnpm add @gonzitech/errly-browser

Node.js:
  pnpm add @gonzitech/errly-node

Next.js:
  pnpm add @gonzitech/errly-nextjs

Session Replay (optional, browser only):
  pnpm add @gonzitech/errly-replay

## Browser – Minimal Setup

```ts
import * as Errly from '@gonzitech/errly-browser';

Errly.init({
  dsn: 'https://<clientKey>@ingest.errly.app/<projectId>',
  environment: 'production',
  release: '1.0.0',
});
```

## Node.js – Minimal Setup

```ts
import * as Errly from '@gonzitech/errly-node';

Errly.init({
  dsn: 'https://<clientKey>@ingest.errly.app/<projectId>',
  environment: 'production',
});
```

## Next.js – Minimal Setup

Step 1 – instrumentation.ts:

```ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const Errly = await import('@gonzitech/errly-nextjs');
    Errly.init({
      dsn: process.env.NEXT_PUBLIC_ERRLY_DSN!,
      environment: process.env.NODE_ENV,
    });
  }
}
```

Step 2 – errly.client.config.ts:

```ts
import * as Errly from '@gonzitech/errly-nextjs';

Errly.init({
  dsn: process.env.NEXT_PUBLIC_ERRLY_DSN!,
  environment: process.env.NODE_ENV,
});
```

Step 3 – app/error.tsx:

```tsx
'use client';
import { captureRouteError } from '@gonzitech/errly-nextjs';
import { useEffect } from 'react';

export default function Error({ error }: { error: Error & { digest?: string } }) {
  useEffect(() => { captureRouteError(error); }, [error]);
  return <h2>Something went wrong</h2>;
}
```

Step 4 – next.config.mjs:

```ts
import { withErrlyConfig } from '@gonzitech/errly-nextjs/config';
export default withErrlyConfig({ /* your config */ });
```

## Session Replay – Minimal Setup

```ts
import { setupErrlyReplay } from '@gonzitech/errly-replay';

setupErrlyReplay({
  dsn: 'https://<clientKey>@ingest.errly.app/<projectId>',
  sessionSampleRate: 0.1,
  maskAllText: true,
});
```

---FULL REFERENCE---

## ErrlyOptions

| Option           | Type                              | Default   | Description                           |
|------------------|-----------------------------------|-----------|---------------------------------------|
| dsn              | string                            | required  | Your project DSN                      |
| environment      | string                            | undefined | e.g. 'production', 'staging'          |
| release          | string                            | undefined | App version or commit SHA             |
| debug            | boolean                           | false     | Log debug info to console             |
| sampleRate       | number                            | 1.0       | Event sample rate (0.0-1.0)           |
| maxBreadcrumbs   | number                            | undefined | Max breadcrumbs to keep               |
| attachStacktrace | boolean                           | undefined | Attach stack trace to message events  |
| beforeSend       | (event: ErrlyEvent) => event|null | undefined | Filter/modify events before sending  |
| integrations     | Integration[]                     | see below | Override default integrations         |

Default integrations:
- errly-browser: GlobalHandlers
- errly-node: OnUncaughtException + OnUnhandledRejection

## ErrlyNextjsOptions (extends ErrlyOptions)

| Option                         | Type    | Default   | Description                                  |
|--------------------------------|---------|-----------|----------------------------------------------|
| autoInstrumentApiRoutes        | boolean | true      | Auto-capture in Pages Router API routes      |
| autoInstrumentServerComponents | boolean | true      | Auto-capture in Server Components            |
| tunnelRoute                    | string  | undefined | Proxy route e.g. '/api/errly-tunnel'         |

## Public API Methods

init(options): void
captureException(error: unknown): string
captureMessage(message: string, level?: 'fatal'|'error'|'warning'|'info'|'debug'): string
setUser(user: { id?, email?, username?, ip_address?, [key: string]: unknown } | null): void
setTag(key: string, value: string): void
setExtra(key: string, value: unknown): void
setContext(key: string, context: Record<string, unknown> | null): void
addBreadcrumb(breadcrumb: { timestamp?, type?, category?, message?, data?, level? }): void
withScope(callback: (scope: Scope) => void): void
flush(timeout?: number): Promise<boolean>

## Next.js Specific

wrapApiHandler(handler) – wraps Pages Router API handler, auto-captures exceptions
wrapServerComponentError(fn) – wraps Server Component, filters redirect/notFound
captureRouteError(error) – use in app/error.tsx
withErrlyConfig(nextConfig) – next.config.mjs wrapper, enables hidden source maps

## ErrlyReplayConfig

| Option            | Type    | Default | Description                         |
|-------------------|---------|---------|-------------------------------------|
| dsn               | string  | required| Your project DSN                    |
| maskAllText       | boolean | false   | Mask all text in recordings         |
| blockAllMedia     | boolean | false   | Block img/video elements            |
| sessionSampleRate | number  | 1.0     | Fraction of sessions to record      |
| flushInterval     | number  | 5000    | Flush interval in ms                |

## Common Patterns

### React Error Boundary
```tsx
import React from 'react';
import * as Errly from '@gonzitech/errly-browser';

class ErrorBoundary extends React.Component<{ children: React.ReactNode }, { hasError: boolean }> {
  constructor(props: { children: React.ReactNode }) {
    super(props);
    this.state = { hasError: false };
  }
  static getDerivedStateFromError() { return { hasError: true }; }
  componentDidCatch(error: Error) { Errly.captureException(error); }
  render() {
    if (this.state.hasError) return <h1>Something went wrong.</h1>;
    return this.props.children;
  }
}
```

### User Context
```ts
Errly.setUser({ id: user.id, email: user.email });
Errly.setUser(null); // on logout
```

### beforeSend Filter
```ts
Errly.init({
  dsn: '...',
  beforeSend(event) {
    if (!event.exception?.values?.[0]?.stacktrace) return null;
    return event;
  },
});
```

### Tags
```ts
Errly.setTag('plan', 'pro');
Errly.setTag('region', 'eu-west');
```