Nuxt

Looking for a step-by-step tutorial? Check out the Nuxt analytics guide.

Good to know

All client-side tracking runs in the browser. For server-side event tracking, see the Server Side Tracking section below.

Installation

Install dependencies

pnpm install @helionlabs/nuxt

Initialize

Add the module to your nuxt.config.ts:

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

Options

Common options

apiUrl - The url of the helion API or your self-hosted instance
clientId - The client id of your application
clientSecret - The client secret of your application (only required for server-side events)
filter - A function that will be called before sending an event. If it returns false, the event will not be sent
disabled - If true, the library will not send any events

Web options

trackScreenViews - If true, the library will automatically track screen views (default: false)
trackOutgoingLinks - If true, the library will automatically track outgoing links (default: false)
trackAttributes - If true, you can trigger events by using html attributes (<button type="button" data-track="your_event" />) (default: false)
sessionReplay - Session replay configuration object (default: disabled). See session replay docs for full options.
- enabled - Enable session replay recording (default: false)
- maskAllInputs - Mask all input field values (default: true)
- maskTextSelector - CSS selector for text elements to mask (default: [data-helion-replay-mask])
- blockSelector - CSS selector for elements to replace with a placeholder (default: [data-helion-replay-block])
- blockClass - Class name that blocks elements from being recorded
- ignoreSelector - CSS selector for elements excluded from interaction tracking
- flushIntervalMs - How often (ms) recorded events are sent to the server (default: 10000)
- maxEventsPerChunk - Maximum events per payload chunk (default: 200)
- maxPayloadBytes - Maximum payload size in bytes (default: 1048576)
- scriptUrl - Custom URL for the replay script (script-tag builds only)

Nuxt options

clientId — Your Helion client ID (required)
apiUrl — API endpoint (default: https://api.helionlabs.dev)
trackScreenViews — Automatically track screen views (default: true)
trackOutgoingLinks — Automatically track outgoing links (default: true)
trackAttributes — Track elements with data-track attributes (default: true)
trackHashChanges — Track URL hash changes (default: false)
disabled — Disable all tracking (default: false)
proxy — Route tracking requests through your server to bypass adblockers (default: false)

Usage

Using the composable

The useHelion composable is auto-imported and available in any component:

<script setup>
const hl = useHelion(); // Auto-imported!

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

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

Accessing via useNuxtApp

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

<script setup>
const { $helionlabs } = useNuxtApp();

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

Tracking Events

Call hl.track() directly, or use data-track attributes on HTML elements for automatic click tracking.

<script setup>
const hl = useHelion();
hl.track('my_event', { foo: 'bar' });
</script>

Identifying Users

Call hl.identify() after authentication to associate the session with a known user profile.

<script setup>
const hl = useHelion();

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

Setting Global Properties

Properties set via setGlobalProperties are attached to every subsequent event.

<script setup>
const hl = useHelion();

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

Incrementing Properties

Increment a numeric property on a user profile. Omit value to increment by 1.

<script setup>
const hl = useHelion();

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

Decrementing Properties

Decrement a numeric property on a user profile. Omit value to decrement by 1.

<script setup>
const hl = useHelion();

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

Clearing User Data

clear() resets the profile, device identity, session, and all group associations. Call it on logout.

<script setup>
const hl = useHelion();

hl.clear();
</script>

Server side

To track server-side events, create a Helion instance from @helionlabs/sdk.

Server-side tracking requires a client secret to authenticate requests. The secret prevents unauthorized event ingestion because CORS headers cannot protect server-to-server calls.

You can reuse the same clientId but must supply the associated clientSecret.

import { Helion } from '@helionlabs/sdk';

const hlServer = new Helion({
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
});

hlServer.track('my_server_event', { ok: true });

// Pass `profileId` to attribute the event to a specific user
hlServer.track('my_server_event', { profileId: '123', ok: true });

Serverless & Edge Functions

In serverless environments, await the tracking call to ensure it completes before the function terminates.

import { Helion } from '@helionlabs/sdk';

const hlServer = new Helion({
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
});

export default defineEventHandler(async (event) => {
  await hlServer.track('my_server_event', { foo: 'bar' });
  return { message: 'Event logged!' };
});

Proxy events

With the proxy option enabled, tracking requests route through your own server, bypassing adblockers that block third-party domains.

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@helionlabs/nuxt'],
  helion: {
    clientId: 'your-client-id',
    proxy: true, // Enables proxy at /api/helion/*
  },
});

When proxy: true is set:

The module automatically sets apiUrl to /api/helion
A server handler is registered at /api/helion/**
All tracking requests route through your server

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

Common options

Web options

On this page