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

# Installation

> Install and configure the Mirador SDK

## Choose Your SDK

Mirador provides two SDKs depending on your environment:

<CardGroup cols={2}>
  <Card title="Web SDK" icon="browser">
    For browser-based applications
  </Card>

  <Card title="Node.js SDK" icon="server">
    For server-side applications
  </Card>
</CardGroup>

<Info>
  SDKs for **Python**, **Go**, **Rust**, and other languages are currently in development. [Contact us](mailto:support@mirador.org) if you're interested in early access.
</Info>

## Web SDK

Install the Mirador Web SDK for browser-based applications:

<CodeGroup>
  ```bash npm theme={null}
  npm install @miradorlabs/web-sdk
  ```

  ```bash yarn theme={null}
  yarn add @miradorlabs/web-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @miradorlabs/web-sdk
  ```
</CodeGroup>

### Initialize the Web Client

```typescript theme={null}
import { Client } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key');
```

## Node.js SDK

Install the Mirador Node.js SDK for server-side applications:

<CodeGroup>
  ```bash npm theme={null}
  npm install @miradorlabs/nodejs-sdk
  ```

  ```bash yarn theme={null}
  yarn add @miradorlabs/nodejs-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @miradorlabs/nodejs-sdk
  ```
</CodeGroup>

### Initialize the Node.js Client

```typescript theme={null}
import { Client } from '@miradorlabs/nodejs-sdk';

const client = new Client('your-api-key');
```

## Configuration

### Custom Gateway URL

If you're using a self-hosted gateway or different environment:

**Web SDK:**

```typescript theme={null}
import { Client } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key', {
  apiUrl: 'https://your-gateway.example.com:443'
});
```

**Node.js SDK:**

```typescript theme={null}
import { Client } from '@miradorlabs/nodejs-sdk';

const client = new Client('your-api-key', {
  apiUrl: 'https://your-gateway.example.com:443'
});
```

### Custom Keep-Alive Interval

Both SDKs support configurable keep-alive intervals:

```typescript theme={null}
const client = new Client('your-api-key', {
  keepAliveIntervalMs: 15000  // Ping every 15 seconds (default: 10000)
});
```

### Debug Mode and Plugins

v2 introduces new client options:

```typescript theme={null}
import { Client, Web3Plugin } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key', {
  debug: true,                                      // Enable debug logging
  plugins: [Web3Plugin({ provider: window.ethereum })],  // Blockchain integration
  sampleRate: 0.5                                   // Record 50% of traces
});
```

See [Client Options](/api-reference/client) for the full list of configuration options.

## Module Formats (Web SDK Only)

The Web SDK provides multiple module formats:

| Format     | File                | Use Case                                |
| ---------- | ------------------- | --------------------------------------- |
| ESM        | `dist/index.esm.js` | Modern bundlers (Webpack, Vite, Rollup) |
| UMD        | `dist/index.umd.js` | Browser globals, older module systems   |
| TypeScript | `dist/index.d.ts`   | Type definitions                        |

### ESM Import

```typescript theme={null}
import { Client } from '@miradorlabs/web-sdk';
```

### CDN / Browser Global

Load the SDK directly from a CDN — no bundler required:

<CodeGroup>
  ```html unpkg theme={null}
  <script src="https://unpkg.com/@miradorlabs/web-sdk@2.0.0/dist/index.umd.js"></script>
  ```

  ```html jsdelivr theme={null}
  <script src="https://cdn.jsdelivr.net/npm/@miradorlabs/web-sdk@2.0.0/dist/index.umd.js"></script>
  ```
</CodeGroup>

Then use the `MiradorWeb` global:

```html theme={null}
<script>
  const client = new MiradorWeb.Client('your-api-key');
</script>
```

<Tip>Pin to a specific version (e.g. `@2.0.0`) in production to avoid unexpected breaking changes.</Tip>

## Browser Requirements

The SDK requires modern browser features:

* **ES2020+** - Modern JavaScript syntax
* **Fetch API** - For network requests
* **Promises** - For async operations

### Supported Browsers

| Browser | Minimum Version |
| ------- | --------------- |
| Chrome  | 80+             |
| Firefox | 75+             |
| Safari  | 13.1+           |
| Edge    | 80+             |

### Polyfills

For older browsers, you may need to include polyfills:

```bash theme={null}
npm install core-js whatwg-fetch
```

```typescript theme={null}
import 'core-js/stable';
import 'whatwg-fetch';
import { Client } from '@miradorlabs/web-sdk';
```

## Verifying Installation

Test that the SDK is working:

**Web SDK:**

```typescript theme={null}
import { Client } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key');
const trace = client.trace({ name: 'TestTrace' })
  .addEvent('installation_verified');

console.log('Web SDK installed successfully!');
```

**Node.js SDK:**

```typescript theme={null}
import { Client } from '@miradorlabs/nodejs-sdk';

const client = new Client('your-api-key');
const trace = client.trace({ name: 'TestTrace' })
  .addEvent('installation_verified');

console.log('Node.js SDK installed successfully!');
```

## Next Steps

<Card title="Quickstart" icon="rocket" href="/quickstart">
  Build your first trace
</Card>