Nuxt

@databuddy/nuxt is a first-class Nuxt module. Add it to nuxt.config.ts once and you're done — pageviews and SPA navigation work automatically with no app.vue changes. Enable trackErrors to also capture JavaScript and Vue component errors.

Install

Run this in your project root. It installs the package and adds it to your nuxt.config.ts automatically:

npx nuxi module add @databuddy/nuxt

Or install manually:

bun add @databuddy/nuxt
# npm install @databuddy/nuxt
# yarn add @databuddy/nuxt
# pnpm add @databuddy/nuxt

Setup

Add your client ID to nuxt.config.ts:

export default defineNuxtConfig({
modules: ["@databuddy/nuxt"],
databuddy: {
  clientId: process.env.NUXT_PUBLIC_DATABUDDY_CLIENT_ID,
},
})

NUXT_PUBLIC_DATABUDDY_CLIENT_ID=your-client-id

That's it. Pageviews and SPA route changes are tracked automatically. No app.vue edits, no plugins to register, no components to place.

Nuxt automatically maps the NUXT_PUBLIC_DATABUDDY_CLIENT_ID environment variable to runtimeConfig.public.databuddy.clientId — no extra configuration needed.

Tracking Events

useDatabuddy is auto-imported in every component:

<script setup>
const { track } = useDatabuddy()

function handleSignup() {
track("signup_clicked", {
  source: "hero",
  plan: "pro",
})
}
</script>

<template>
<button @click="handleSignup">Get started</button>
</template>

Full composable API

All functions are available from useDatabuddy():

Function	Description
`track(name, properties?)`	Track a custom event
`trackError(message, properties?)`	Track an error
`screenView(properties?)`	Manually trigger a pageview
`setGlobalProperties(properties)`	Attach properties to all future events
`clear()`	Reset anonymous and session IDs (call after logout)
`flush()`	Force-send all queued events immediately
`getAnonymousId()`	Get the current anonymous user ID
`getSessionId()`	Get the current session ID
`getTrackingIds()`	Get both IDs at once
`getTrackingParams()`	Get IDs as a URL query string for cross-domain tracking

Options API and templates

$databuddy is available directly in templates and Options API components — no import needed:

<template>
<button @click="$databuddy.track('cta_clicked')">Sign up</button>
</template>

export default defineComponent({
methods: {
  handleClick() {
    this.$databuddy.track("cta_clicked")
  },
},
})

Feature Flags

Add the flags config to enable the flag composables:

export default defineNuxtConfig({
modules: ["@databuddy/nuxt"],
databuddy: {
  clientId: process.env.NUXT_PUBLIC_DATABUDDY_CLIENT_ID,
  flags: {}, // clientId is inherited automatically
},
})

Then use useFlag and useFlags — auto-imported everywhere:

<script setup>
const { on: isNewCheckout, loading } = useFlag("new-checkout")
</script>

<template>
<template v-if="loading">
  <CheckoutSkeleton />
</template>
<template v-else-if="isNewCheckout">
  <NewCheckout />
</template>
<template v-else>
  <LegacyCheckout />
</template>
</template>

Module options

All options are passed under the databuddy key in nuxt.config.ts:

Option	Type	Default	Description
`clientId`	`string`	—	Your Databuddy client ID
`disabled`	`boolean`	`false`	Disable all tracking
`debug`	`boolean`	`false`	Enable verbose logging
`trackWebVitals`	`boolean`	`false`	Core Web Vitals (LCP, CLS, TTFB)
`trackErrors`	`boolean`	`false`	JS errors + Vue component errors
`trackOutgoingLinks`	`boolean`	`false`	Clicks on external links
`trackInteractions`	`boolean`	`false`	Button clicks and form submissions
`trackAttributes`	`boolean`	`false`	Elements with `data-track` attribute
`trackPerformance`	`boolean`	`true`	Page load timing
`maskPatterns`	`string[]`	`[]`	Glob patterns to anonymise paths
`skipPatterns`	`string[]`	`[]`	Glob patterns to skip entirely
`samplingRate`	`number`	`1.0`	Event sampling rate (0.0–1.0)
`flags`	`FlagsConfig`	—	Feature flag configuration

Privacy

export default defineNuxtConfig({
modules: ["@databuddy/nuxt"],
databuddy: {
  clientId: process.env.NUXT_PUBLIC_DATABUDDY_CLIENT_ID,
  // Never track admin or internal routes
  skipPatterns: ["/admin/**", "/internal/*"],
  // Anonymise user IDs in paths
  maskPatterns: ["/users/*", "/orders/**"],
},
})

Disable in development

export default defineNuxtConfig({
modules: ["@databuddy/nuxt"],
databuddy: {
  clientId: process.env.NUXT_PUBLIC_DATABUDDY_CLIENT_ID,
  disabled: process.env.NODE_ENV !== "production",
},
})