Skip to main content

​
Installation

npm install --save @outlit/browser

​
Quick Start

Create a Nuxt plugin to initialize Outlit: 
// plugins/outlit.client.ts
import outlit from '@outlit/browser'

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig()

  outlit.init({
    publicKey: config.public.outlitKey,
    trackPageviews: true,
  })

  return {
    provide: {
      outlit
    }
  }
})
Configure your runtime config: 
// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      outlitKey: process.env.NUXT_PUBLIC_OUTLIT_KEY
    }
  }
})
Add your public key to .env:
NUXT_PUBLIC_OUTLIT_KEY=pk_your_public_key_here

​
Tracking Events

Track events using the provided instance: 
<script setup>
const { $outlit } = useNuxtApp()

function handleClick() {
  $outlit.track('button_clicked', {
    button: 'cta',
    page: 'pricing'
  })
}
</script>

<template>
  <button @click="handleClick">
    Get Started
  </button>
</template>

​
Creating a Composable

Create a reusable composable for better DX: 
// composables/useOutlit.ts
export function useOutlit() {
  const { $outlit } = useNuxtApp()

  function track(eventName: string, properties?: Record<string, any>) {
    $outlit.track(eventName, properties)
  }

  function identify(email: string, traits?: Record<string, any>) {
    $outlit.identify({ email, traits })
  }

  function setUser(identity: { email?: string; userId?: string; traits?: Record<string, any> }) {
    $outlit.setUser(identity)
  }

  function clearUser() {
    $outlit.clearUser()
  }

  return {
    track,
    identify,
    setUser,
    clearUser
  }
}
Use in components: 
<script setup>
const { track } = useOutlit()

function handleFeatureClick() {
  track('feature_used', { feature: 'export' })
}
</script>

<template>
  <button @click="handleFeatureClick">
    Export Data
  </button>
</template>

​
Identifying Users

Identify users after authentication: 
<script setup>
const { identify } = useOutlit()
const router = useRouter()

async function handleLogin(email: string, password: string) {
  const user = await $fetch('/api/auth/login', {
    method: 'POST',
    body: { email, password }
  })

  identify(user.email, {
    name: user.name,
    plan: user.plan
  })

  router.push('/dashboard')
}
</script>

​
Auth Integration

​
With Nuxt Auth

// plugins/outlit.client.ts
import outlit from '@outlit/browser'

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig()
  const { data: auth } = useAuth()

  outlit.init({
    publicKey: config.public.outlitKey,
    trackPageviews: true,
  })

  // Sync user identity with auth state
  watch(
    () => auth.value,
    (session) => {
      if (session?.user) {
        outlit.setUser({
          email: session.user.email,
          userId: session.user.id,
          traits: {
            name: session.user.name
          }
        })
      } else {
        outlit.clearUser()
      }
    },
    { immediate: true }
  )

  return {
    provide: { outlit }
  }
})

​
With Supabase

// plugins/outlit.client.ts
import outlit from '@outlit/browser'

export default defineNuxtPlugin(async () => {
  const config = useRuntimeConfig()
  const supabase = useSupabaseClient()
  const user = useSupabaseUser()

  outlit.init({
    publicKey: config.public.outlitKey,
    trackPageviews: true,
  })

  // Sync user identity
  watch(
    user,
    (currentUser) => {
      if (currentUser) {
        outlit.setUser({
          email: currentUser.email!,
          userId: currentUser.id,
          traits: {
            name: currentUser.user_metadata?.name
          }
        })
      } else {
        outlit.clearUser()
      }
    },
    { immediate: true }
  )

  return {
    provide: { outlit }
  }
})

​
Router Integration

Track route changes: 
// plugins/outlit.client.ts
import outlit from '@outlit/browser'

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig()
  const router = useRouter()

  outlit.init({
    publicKey: config.public.outlitKey,
    trackPageviews: false, // Manual pageview tracking
  })

  // Track pageviews on route change
  router.afterEach((to) => {
    outlit.track('pageview', {
      path: to.path,
      name: to.name,
      params: to.params,
      query: to.query
    })
  })

  return {
    provide: { outlit }
  }
})

​
Server-Side Tracking

Track events from server API routes: 
// server/api/checkout.post.ts
import { Outlit } from '@outlit/node'

const outlit = new Outlit({
  privateKey: process.env.OUTLIT_PRIVATE_KEY!
})

export default defineEventHandler(async (event) => {
  const body = await readBody(event)

  await outlit.track({
    visitorId: body.userId,
    event: 'checkout_completed',
    properties: {
      amount: body.amount,
      plan: body.plan
    }
  })

  return { success: true }
})
For server-side tracking, see the Node.js integration guide.

​
Journey Stage Events

Track user lifecycle: 
<script setup>
const { activate, paid } = useOutlit()

function handleOnboardingComplete() {
  activate({ flow: 'onboarding', step: 'completed' })
}

function handleSubscribe(plan: string, amount: number) {
  paid({ plan, amount })
}
</script>
Stage methods (activate, engaged, paid, churned) require the user to be identified first.
Handle user consent: 
<script setup>
const showBanner = ref(false)
const { $outlit } = useNuxtApp()

onMounted(() => {
  const hasConsent = localStorage.getItem('tracking-consent')
  if (hasConsent !== 'true') {
    showBanner.value = true
  }
})

function acceptTracking() {
  localStorage.setItem('tracking-consent', 'true')
  $outlit.enableTracking()
  showBanner.value = false
}
</script>

<template>
  <div v-if="showBanner" class="cookie-banner">
    <p>We use cookies to improve your experience.</p>
    <button @click="acceptTracking">Accept</button>
  </div>
</template>
Initialize without auto-tracking: 
// plugins/outlit.client.ts
import outlit from '@outlit/browser'

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig()

  outlit.init({
    publicKey: config.public.outlitKey,
    autoTrack: false, // Wait for consent
  })

  return {
    provide: { outlit }
  }
})

​
Environment Variables

Configure environment variables: 
# .env

# Public key (used in browser)
NUXT_PUBLIC_OUTLIT_KEY=pk_your_public_key_here

# Private key (used in server API routes)
OUTLIT_PRIVATE_KEY=sk_your_private_key_here
Never expose your private key in client-side code. Only use it in server API routes.

​
TypeScript Support

Full TypeScript support is included: 
// plugins/outlit.client.ts
import outlit, { type OutlitOptions } from '@outlit/browser'

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig()

  const options: OutlitOptions = {
    publicKey: config.public.outlitKey,
    trackPageviews: true,
    flushInterval: 5000
  }

  outlit.init(options)

  return {
    provide: { outlit }
  }
})

​
Next Steps

Vue Integration

Use Outlit with Vue 3

Server-Side Tracking

Track events from your backend

Identity Resolution

Learn how profiles are merged

NPM Package

Full API reference