billdogeng-nuxt

The BillDog engagement suite for Nuxt / Vue — a thin, SSR-safe, idiomatic wrapper over the existing browser SDKs (@billdog.io/web, @billdog.io/analytics, @billdog.io/survey-core).

It surfaces everything the engagement suite offers the Vue way:

• Analytics — capture, identify, group
• Surveys — fetch, render (<BilldogSurvey/>), and submit (useSurvey)
• In-app messaging — trigger placements
• Feature flags — remote / server-authoritative (useFeatureFlag)

Feature flags are evaluated on the BillDog backend. This package does no local bucketing and contains no murmurhash — targeting is server-side only.

Install

npm install billdogeng-nuxt @billdog.io/web @billdog.io/analytics @billdog.io/survey-core

vue is a peer dependency (provided by Nuxt). The three BillDog browser SDKs are optional peers — install the ones whose features you use.

Setup (Nuxt module — recommended)

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['billdogeng-nuxt/module'],
  billdog: {
    apiKey: process.env.NUXT_PUBLIC_BILLDOG_API_KEY,
    projectId: process.env.NUXT_PUBLIC_BILLDOG_PROJECT_ID,
    customerId: 'user_42', // optional; or call identify() later
  },
});

The module registers a client-only plugin, so the engagement client is created in the browser only — it never runs during SSR and never touches window/document on the server. It also auto-imports the composables and registers <BilldogSurvey/> globally, so you can use them anywhere without imports.

Manual setup (plain Vue, or to control plugin order)

import { createApp } from 'vue';
import { createBilldog } from 'billdogeng-nuxt';
import App from './App.vue';

const app = createApp(App);
app.use(
  createBilldog({
    config: { apiKey: '...', projectId: '...' },
  }),
);
app.mount('#app');

Analytics

<script setup lang="ts">
import { useBilldog } from 'billdogeng-nuxt'; // auto-imported under the module

const { capture, identify, group } = useBilldog();

function onBuy() {
  identify('user_42', { plan: 'pro' });
  group('company', 'acme', { seats: 12 });
  capture('checkout_started', { value: 49.0 });
}
</script>

<template>
  <button @click="onBuy">Buy</button>
</template>

Feature flags (remote)

useFeatureFlag returns a reactive Ref whose value comes from the backend's flag-evaluation response, and updates automatically whenever the SDK re-evaluates flags.

<script setup lang="ts">
import { useFeatureFlag } from 'billdogeng-nuxt';

const newBanner = useFeatureFlag('new-banner', false); // Ref<boolean>
const theme = useFeatureFlag('home-theme', 'classic'); // Ref<string variant>
</script>

<template>
  <div v-if="newBanner" :class="`banner banner--${theme}`">Welcome!</div>
</template>

Surveys

Drop-in component:

<template>
  <BilldogSurvey
    survey-id="svy_nps"
    @submit="(r) => console.log('submitted', r.responseId)"
  />
</template>

Or build your own UI with the composable + default slot:

<script setup lang="ts">
import { useSurvey } from 'billdogeng-nuxt';

const { survey, loading, submit } = useSurvey('svy_nps');
</script>

<template>
  <button
    v-if="!loading && survey"
    @click="submit([{ question_id: 'q1', answer_number: 9 }])"
  >
    Rate 9 — {{ survey.name }}
  </button>
</template>

The default slot of <BilldogSurvey/> receives the full render state ({ survey, loading, error, answers, setAnswer, submit, submitting, submitted }) for fully custom markup.

In-app messaging

<script setup lang="ts">
import { useBilldog } from 'billdogeng-nuxt';
const { showInAppMessages } = useBilldog();
</script>

<template>
  <button @click="showInAppMessages('help-center')">Help</button>
</template>

API

| Export | Kind | Purpose | | --- | --- | --- | | billdogeng-nuxt/module | Nuxt module | Wires everything (client-only plugin, auto-imports, component). | | createBilldog({ config }) | fn | Vue plugin for manual app.use(...). | | useBilldog() | composable | { client, ready, capture, identify, group, showInAppMessages, reset }. | | useFeatureFlag(key, default) | composable | Ref of a remote flag (boolean or string variant). | | useFeatureEnabled(key) | composable | Ref<boolean> view of a remote flag. | | useSurvey(surveyId) | composable | { survey, loading, error, submit, refetch }. | | <BilldogSurvey survey-id /> | component | Fetch + render + submit a survey. | | createBilldogClient(config, deps?) | fn | Low-level client builder (advanced). |

SSR

Everything is SSR-safe. The module's plugin is mode: 'client', so the engagement client only instantiates in the browser. During SSR the composables resolve to a null client with ready === false — all helpers no-op and reactive values hold their defaults, so server-rendered HTML is deterministic and never touches window/document.

License

MIT