Nuxt

Install HumanBehavior in Nuxt with a browser-only plugin and public runtime config.

Nuxt runs code on both server and client, so HumanBehavior belongs in a .client.ts plugin. The plugin reads Nuxt public runtime config and never imports the SDK into the server renderer.

Wizard detection

The wizard detects Nuxt when it sees:

Signal	Details
`nuxt` dependency	Version read from `package.json`
`nuxt.config.js` / `.ts` / `.mjs` / `.cjs`	Works even when dependency parsing is incomplete

Nuxt is checked before standalone Vue, so Nuxt projects do not fall through to the Vue guide.

Package

pnpm add humanbehavior-js

Environment variables

NUXT_PUBLIC_HUMANBEHAVIOR_API_KEY=your-api-key
NUXT_PUBLIC_HUMANBEHAVIOR_INGESTION_URL=https://ingest.humanbehavior.co

Nuxt exposes NUXT_PUBLIC_* values to runtimeConfig.public. Non-public env vars are server-only and cannot initialize the browser SDK.

Wire runtime config

In nuxt.config.ts:

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      humanbehaviorApiKey: process.env.NUXT_PUBLIC_HUMANBEHAVIOR_API_KEY,
      humanbehaviorIngestionUrl:
        process.env.NUXT_PUBLIC_HUMANBEHAVIOR_INGESTION_URL,
    },
  },
});

Init in `plugins/humanbehavior.client.ts`

import { HumanBehaviorTracker } from "humanbehavior-js";

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  const apiKey = config.public.humanbehaviorApiKey as string | undefined;
  if (!apiKey) return;

  HumanBehaviorTracker.init(apiKey, {
    ingestionUrl: config.public.humanbehaviorIngestionUrl as string | undefined,
  });
});

The .client.ts suffix is the important part. It tells Nuxt to run this plugin only in the browser.

Why not `import.meta.server` in a universal plugin?

An import.meta.server guard can work, but the wizard reference project uses .client.ts because it is harder to accidentally regress:

Pattern	Status
`plugins/humanbehavior.client.ts`	Recommended
Universal plugin with `if (import.meta.server) return`	Acceptable but easier to break
Init in `nuxt.config.ts`	Wrong: config runs outside the browser
Init in server middleware	Wrong

Nuxt app placement

You do not need to edit layouts or wrap <NuxtPage />. Nuxt auto-registers plugins under plugins/.

Expected files:

nuxt.config.ts
plugins/
  humanbehavior.client.ts

Options to consider

HumanBehaviorTracker.init(apiKey, {
  ingestionUrl: config.public.humanbehaviorIngestionUrl as string | undefined,
  environment: config.public.environment as string | undefined,
  release: config.public.release as string | undefined,
  redactionStrategy: { mode: "visibility-first" },
});

Only put values in runtimeConfig.public when they are safe to expose to browser code. Project API keys are browser credentials; private server secrets are not.

Nuxt router navigations use browser history. The SDK's navigation capture handles ordinary route changes automatically.

If your app uses custom navigation that does not touch history, retain the tracker and call trackPageView() after route changes:

export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig();
  const apiKey = config.public.humanbehaviorApiKey as string | undefined;
  if (!apiKey) return;

  const tracker = HumanBehaviorTracker.init(apiKey);
  nuxtApp.hook("page:finish", () => {
    void tracker.trackPageView();
  });
});

Most Nuxt apps do not need that hook.

Common pitfalls

Pitfall	Symptom	Fix
Using `VITE_` vars in Nuxt	Config value missing	Use `NUXT_PUBLIC_*`
Reading `process.env` directly in plugin	Value missing in client bundle	Map through `runtimeConfig.public`
File named `humanbehavior.ts` instead of `.client.ts`	SSR import/runtime issues	Rename plugin to `.client.ts`
Initializing in a component	Duplicate init on remount	Use one plugin
Local ingestion points at dashboard	Network failures	Use actual ingestion host or reverse proxy

Verify

Restart Nuxt after env changes.
Open the site in a browser.
Confirm /api/ingestion/events and /heartbeat return 2xx (init is not required).
Navigate between routes.
Check Replays for a session and Dashboard for page activity.

Troubleshooting checklist: Verify data is flowing.

What the wizard writes

The wizard's Nuxt framework config provides:

Field	Value
Integration	`nuxt`
Reference project key	`nuxt`
Env vars	`NUXT_PUBLIC_HUMANBEHAVIOR_API_KEY`, `NUXT_PUBLIC_HUMANBEHAVIOR_INGESTION_URL`
Project detection prompt	Look for `nuxt` dependency and/or `nuxt.config.*`

It installs the runtime package and prompts the agent toward the client plugin pattern above.