Overview

Pick your framework for shipped SDK placement, public environment variable names, wizard detection, and client-only init rules.

HumanBehavior's browser SDK is one package, but safe installation is framework-specific: the key must be public to the browser, the tracker must initialize only in client code, and SSR frameworks need a leaf initializer rather than a root markup wrapper.

The runtime package is always humanbehavior-js. The wizard package is @humanbehavior/wizard and targets the same runtime package.

Choose your guide

Framework	Wizard detection truth	Public env vars	Entry point to edit	Guide
React	`react` dependency, excluding Next/Gatsby/Remix/React Router meta-frameworks	`VITE_HUMANBEHAVIOR_API_KEY`, `VITE_HUMANBEHAVIOR_INGESTION_URL`	Vite/CRA client entry such as `src/main.tsx`	React
Next.js	`next` dependency or `next.config.*`; asks App vs Pages router if ambiguous	`NEXT_PUBLIC_HUMANBEHAVIOR_API_KEY`, `NEXT_PUBLIC_HUMANBEHAVIOR_INGESTION_URL`	App Router leaf client component; Pages Router custom app/client hook	Next.js
Vue	`vue` dependency and no `nuxt` dependency	`VITE_HUMANBEHAVIOR_API_KEY`, `VITE_HUMANBEHAVIOR_INGESTION_URL`	`src/main.ts` before `createApp(...).mount(...)`	Vue
Nuxt	`nuxt` dependency or `nuxt.config.*`	`NUXT_PUBLIC_HUMANBEHAVIOR_API_KEY`, `NUXT_PUBLIC_HUMANBEHAVIOR_INGESTION_URL`	`plugins/humanbehavior.client.ts`	Nuxt
Angular	`@angular/core` dependency or `angular.json`	`NG_APP_HUMANBEHAVIOR_API_KEY`, `NG_APP_HUMANBEHAVIOR_INGESTION_URL`	Browser bootstrap such as `src/main.ts`	Angular
Svelte / SvelteKit	`svelte`, `@sveltejs/kit`, or `svelte.config.*`	`PUBLIC_HUMANBEHAVIOR_API_KEY`, `PUBLIC_HUMANBEHAVIOR_INGESTION_URL`	SvelteKit `+layout.svelte` `onMount` or SPA client entry	Svelte
Remix / React Router 7	`@remix-run/react` or `@react-router/dev`	`HUMANBEHAVIOR_API_KEY`, `HUMANBEHAVIOR_INGESTION_URL` passed to browser via `window.ENV`	`app/entry.client.tsx`	Remix
Gatsby	`gatsby` dependency or `gatsby-config.*`	`GATSBY_HUMANBEHAVIOR_API_KEY`, `GATSBY_HUMANBEHAVIOR_INGESTION_URL`	`gatsby-browser.tsx` `onClientEntry`	Gatsby
Astro	`astro` dependency or `astro.config.*`	`PUBLIC_HUMANBEHAVIOR_API_KEY`, `PUBLIC_HUMANBEHAVIOR_INGESTION_URL`	Client script in an Astro component rendered by a shared layout	Astro
HTML / Vanilla JS	`index.html`, `public/index.html`, or `src/index.html` with scripts	Vite-bundled example uses `VITE_HUMANBEHAVIOR_API_KEY`, `VITE_HUMANBEHAVIOR_INGESTION_URL`	Bundled browser script such as `src/main.js`	HTML

What is common across every framework

Install humanbehavior-js with your project package manager.
Put the API key in a browser-exposed env var for the framework.
Initialize once, in browser code only.
Pass options.ingestionUrl only when overriding the default hosted ingestion URL.
Verify with live ingestion requests and a replay row.

import { HumanBehaviorTracker } from "humanbehavior-js";

HumanBehaviorTracker.init(apiKey, {
  ingestionUrl,
  redactionStrategy: { mode: "visibility-first" },
});

Do not invent an endpoint prop. The SDK option is ingestionUrl.

Wizard coverage

The shipped wizard supports these integrations, in this detection order:

nextjs
nuxt
vue
remix
svelte
angular
astro
gatsby
react
html

Specific meta-frameworks come before generic fallbacks. That is why a Next.js app with react is detected as Next.js, not generic React.

Run:

npx @humanbehavior/wizard@latest

Useful install flags are documented in Wizard installer. The wizard can choose package manager, install humanbehavior-js, add env vars through its env tools, run project-native checks, and write humanbehavior-install-report.md.

Hydration rule for SSR frameworks

SSR frameworks need a client-only placement:

Pattern	Status
Leaf initializer that returns `null` and calls `HumanBehaviorTracker.init` in `useEffect` / `onMount` / client plugin	Recommended
Initializing from server component, loader, server entry, Astro frontmatter, Gatsby SSR, or Nuxt universal plugin	Wrong
Wrapping the root SSR tree with `HumanBehaviorProvider`	Avoid for App Router / hydration-sensitive roots

The React provider is shipped and useful in purely client-rendered React apps. SSR React frameworks should prefer the leaf initializer to avoid shifting generated attributes during hydration.

Env var quick reference

Framework family	Browser-exposed names
Vite React / Vue / bundled HTML	`VITE_HUMANBEHAVIOR_API_KEY`, `VITE_HUMANBEHAVIOR_INGESTION_URL`
Next.js	`NEXT_PUBLIC_HUMANBEHAVIOR_API_KEY`, `NEXT_PUBLIC_HUMANBEHAVIOR_INGESTION_URL`
Nuxt	`NUXT_PUBLIC_HUMANBEHAVIOR_API_KEY`, `NUXT_PUBLIC_HUMANBEHAVIOR_INGESTION_URL`
SvelteKit / Astro	`PUBLIC_HUMANBEHAVIOR_API_KEY`, `PUBLIC_HUMANBEHAVIOR_INGESTION_URL`
Gatsby	`GATSBY_HUMANBEHAVIOR_API_KEY`, `GATSBY_HUMANBEHAVIOR_INGESTION_URL`
Angular	`NG_APP_HUMANBEHAVIOR_API_KEY`, `NG_APP_HUMANBEHAVIOR_INGESTION_URL`
Remix	`HUMANBEHAVIOR_API_KEY`, `HUMANBEHAVIOR_INGESTION_URL`, handed to `window.ENV`

Verification

After installation, use Verify data is flowing. A successful install shows at least one of:

ingestion requests with 2xx status
a new row in Replays
non-zero Dashboard activity in the selected range
Installation Verify showing live events or a live preview