@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. Set autocapture: { errors: true } 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

The module tracks pageviews and route changes without any app.vue edits or plugins.

Nuxt automatically maps the NUXT_PUBLIC_DATABUDDY_CLIENT_ID environment variable to runtimeConfig.public.databuddy.clientId, so no extra configuration is 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(error, properties?)`	Track an error, from an `Error` or a message
`screenView(properties?)`	Manually trigger a pageview
`setGlobalProperties(properties)`	Attach properties to all future events
`identify(userId, traits?)`	Link this browser to a user ID from your system
`reset()`	Forget the user and reset anonymous and session IDs (call after logout)
`flush()`	Force-send all queued events immediately
`getIds()`	Get `{ anonymousId, sessionId, profileId }`
`getTrackingParams()`	Get IDs as a URL query string for cross-domain tracking
`optOut()`, `optIn()`	Stop or resume tracking this visitor; visitors with Global Privacy Control or Do Not Track stay untracked

Options API and templates

$databuddy is available directly in templates and Options API components with 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, which are 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. The grouped names (autocapture, batching, retries, sampleRate, skipPaths, maskPaths) need @databuddy/nuxt 3.1.0 or later; the flat names they replace still work.

Option	Type	Default	Description
`clientId`	`string`	-	Your Databuddy Client ID
`disabled`	`boolean`	`false`	Disable all tracking
`debug`	`boolean`	`false`	Enable verbose logging
`autocapture`	`boolean \| object`	`{ interactions: true }`	What to record besides pageviews: `webVitals`, `errors` (JS errors + Vue component errors), `outgoingLinks`, `interactions`, `attributes`, `hashChanges`
`maskPaths`	`string[]`	`[]`	Glob patterns to anonymise paths
`skipPaths`	`string[]`	`[]`	Glob patterns to skip entirely
`sampleRate`	`number`	`1`	Fraction of automatic pageview and page-exit events sent, from 0 to 1, decided per event; `track()` events are not sampled
`flags`	`FlagsConfig`	-	Feature flag configuration

The module also accepts the other browser options (batching, retries, replay, scriptUrl, ...) except filter, because runtime config can't hold functions.

Privacy

export default defineNuxtConfig({
modules: ["@databuddy/nuxt"],
databuddy: {
  clientId: process.env.NUXT_PUBLIC_DATABUDDY_CLIENT_ID,
  // Never track admin or internal routes
  skipPaths: ["/admin/**", "/internal/*"],
  // Anonymise user IDs in paths
  maskPaths: ["/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",
},
})

Vue SDK

Component-based integration for plain Vue 3 apps

Feature flags

Complete feature flag documentation

Tracker helpers

track, flush, getIds, and more

SDK configuration

Full configuration reference

Nuxt

On this page