stats/apps/public/content/docs/(tracking)/sdks/nuxt.mdx

---
title: Nuxt
---

import Link from 'next/link';
import { Step, Steps } from 'fumadocs-ui/components/steps';

import { DeviceIdWarning } from '@/components/device-id-warning';
import { PersonalDataWarning } from '@/components/personal-data-warning';
import { Callout } from 'fumadocs-ui/components/callout';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
import WebSdkConfig from '@/components/web-sdk-config.mdx';

<Callout>
Looking for a step-by-step tutorial? Check out the [Nuxt analytics guide](/guides/nuxt-analytics).
</Callout>

## Good to know

Keep in mind that all tracking here happens on the client!

Read more about server side tracking in the [Server Side Tracking](#track-server-events) section.

## Installation

<Steps>
### Install dependencies

```bash
pnpm install @openpanel/nuxt
```

### Initialize

Add the module to your `nuxt.config.ts`:

```typescript
export default defineNuxtConfig({
  modules: ['@openpanel/nuxt'],
  openpanel: {
    clientId: 'your-client-id',
    trackScreenViews: true,
    trackOutgoingLinks: true,
    trackAttributes: true,
  },
});
```

#### Options

<CommonSdkConfig />
<WebSdkConfig />

##### Nuxt options

- `clientId` - Your OpenPanel client ID (required)
- `apiUrl` - The API URL to send events to (default: `https://api.openpanel.dev`)
- `trackScreenViews` - Automatically track screen views (default: `true`)
- `trackOutgoingLinks` - Automatically track outgoing links (default: `true`)
- `trackAttributes` - Automatically track elements with `data-track` attributes (default: `true`)
- `trackHashChanges` - Track hash changes in URL (default: `false`)
- `disabled` - Disable tracking (default: `false`)
- `proxy` - Enable server-side proxy to avoid adblockers (default: `false`)

</Steps>

## Usage

### Using the composable

The `useOpenPanel` composable is auto-imported, so you can use it directly in any component:

```vue
<script setup>
const op = useOpenPanel(); // Auto-imported!

function handleClick() {
  op.track('button_click', { button: 'signup' });
}
</script>

<template>
  <button @click="handleClick">Trigger event</button>
</template>
```

### Accessing via useNuxtApp

You can also access the OpenPanel instance directly via `useNuxtApp()`:

```vue
<script setup>
const { $openpanel } = useNuxtApp();

$openpanel.track('my_event', { foo: 'bar' });
</script>
```

### Tracking Events

You can track events with two different methods: by calling the `op.track()` method directly or by adding `data-track` attributes to your HTML elements.

```vue
<script setup>
const op = useOpenPanel();
op.track('my_event', { foo: 'bar' });
</script>
```

### Identifying Users

To identify a user, call the `op.identify()` method with a unique identifier.

```vue
<script setup>
const op = useOpenPanel();

op.identify({
  profileId: '123', // Required
  firstName: 'Joe',
  lastName: 'Doe',
  email: 'joe@doe.com',
  properties: {
    tier: 'premium',
  },
});
</script>
```

### Setting Global Properties

To set properties that will be sent with every event:

```vue
<script setup>
const op = useOpenPanel();

op.setGlobalProperties({
  app_version: '1.0.2',
  environment: 'production',
});
</script>
```

### Incrementing Properties

To increment a numeric property on a user profile.

- `value` is the amount to increment the property by. If not provided, the property will be incremented by 1.

```vue
<script setup>
const op = useOpenPanel();

op.increment({
  profileId: '1',
  property: 'visits',
  value: 1, // optional
});
</script>
```

### Decrementing Properties

To decrement a numeric property on a user profile.

- `value` is the amount to decrement the property by. If not provided, the property will be decremented by 1.

```vue
<script setup>
const op = useOpenPanel();

op.decrement({
  profileId: '1',
  property: 'visits',
  value: 1, // optional
});
</script>
```

### Clearing User Data

To clear the current user's data:

```vue
<script setup>
const op = useOpenPanel();

op.clear();
</script>
```

## Server side

If you want to track server-side events, you should create an instance of our Javascript SDK. Import `OpenPanel` from `@openpanel/sdk`

<Callout>
When using server events it's important that you use a secret to authenticate the request. This is to prevent unauthorized requests since we cannot use cors headers.

You can use the same clientId but you should pass the associated client secret to the SDK.

</Callout>

```typescript
import { OpenPanel } from '@openpanel/sdk';

const opServer = new OpenPanel({
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
});

opServer.track('my_server_event', { ok: '✅' });

// Pass `profileId` to track events for a specific user
opServer.track('my_server_event', { profileId: '123', ok: '✅' });
```

### Serverless & Edge Functions

If you log events in a serverless environment, make sure to await the event call to ensure it completes before the function terminates.

```typescript
import { OpenPanel } from '@openpanel/sdk';

const opServer = new OpenPanel({
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
});

export default defineEventHandler(async (event) => {
  // Await to ensure event is logged before function completes
  await opServer.track('my_server_event', { foo: 'bar' });
  return { message: 'Event logged!' };
});
```

### Proxy events

With the `proxy` option enabled, you can proxy your events through your server, which ensures all events are tracked since many adblockers block requests to third-party domains.

```typescript title="nuxt.config.ts"
export default defineNuxtConfig({
  modules: ['@openpanel/nuxt'],
  openpanel: {
    clientId: 'your-client-id',
    proxy: true, // Enables proxy at /api/openpanel/*
  },
});
```

When `proxy: true` is set:
- The module automatically sets `apiUrl` to `/api/openpanel`
- A server handler is registered at `/api/openpanel/**`
- All tracking requests route through your server

This helps bypass adblockers that might block requests to `api.openpanel.dev`.