Astro

Install HumanBehavior in Astro with a client script component rendered by your shared layout.

Astro frontmatter runs on the server. HumanBehavior must initialize from a browser script, typically in a tiny Astro component rendered once by a shared layout.

Wizard detection

The wizard detects Astro when it sees:

Signal	Details
`astro` dependency	Version read from `package.json`
`astro.config.js` / `.ts` / `.mjs` / `.cjs`	Config-file fallback

The wizard uses PUBLIC_ env vars, matching Astro's client exposure convention.

Package

pnpm add humanbehavior-js

Environment variables

PUBLIC_HUMANBEHAVIOR_API_KEY=your-api-key
PUBLIC_HUMANBEHAVIOR_INGESTION_URL=https://ingest.humanbehavior.co

Only PUBLIC_ variables are available to browser scripts through import.meta.env.

Create `src/components/HumanBehavior.astro`

---
// Astro frontmatter runs on the server. Do not initialize the browser SDK here.
---

<script>
  import { HumanBehaviorTracker } from "humanbehavior-js";

  const apiKey = import.meta.env.PUBLIC_HUMANBEHAVIOR_API_KEY;
  if (apiKey) {
    HumanBehaviorTracker.init(apiKey, {
      ingestionUrl: import.meta.env.PUBLIC_HUMANBEHAVIOR_INGESTION_URL,
    });
  }
</script>

The <script> is bundled for the browser. It can import humanbehavior-js safely because it does not run in server frontmatter.

Render it once in a shared layout

---
import HumanBehavior from "../components/HumanBehavior.astro";
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <HumanBehavior />
  </head>
  <body>
    <slot />
  </body>
</html>

The reference project puts the component in <head> so the client script is included across pages. Rendering it inside <body> is also fine if that matches your layout conventions.

Astro islands and client directives

You do not need client:load on the HumanBehavior component shown above. The component itself contributes a browser script.

Use client:load only if you wrap the SDK in a framework island (React/Vue/Svelte component). If you do that, the same rule applies: initialize once and only in browser code.

What not to do

Pattern	Why
`HumanBehaviorTracker.init` in frontmatter	Frontmatter runs on server/build
Reading non-`PUBLIC_` env vars in script	Not exposed to browser
Rendering initializer only on one page	Other pages may not record
Adding a raw CDN snippet from memory	The shipped docs/wizard target the npm package

Options example

<script>
  import { HumanBehaviorTracker } from "humanbehavior-js";

  const apiKey = import.meta.env.PUBLIC_HUMANBEHAVIOR_API_KEY;
  if (apiKey) {
    HumanBehaviorTracker.init(apiKey, {
      ingestionUrl: import.meta.env.PUBLIC_HUMANBEHAVIOR_INGESTION_URL,
      release: import.meta.env.PUBLIC_APP_VERSION,
      environment: import.meta.env.PUBLIC_DEPLOY_ENV,
      redactionStrategy: { mode: "visibility-first" },
    });
  }
</script>

Only expose release/environment values that are safe for client code.

Multi-page behavior

Astro can ship mostly static pages. The SDK records sessions in the browser:

Navigation type	Behavior
Full page load	New browser page initializes and continues/rotates session according to SDK session rules
Client-side transition	Browser history capture records navigation
Island interaction	Clicks/forms/errors are captured like any browser UI

Common pitfalls

Pitfall	Symptom	Fix
Init in frontmatter	Build or server error	Move to `<script>`
Missing `PUBLIC_` prefix	`apiKey` undefined	Rename env var
Component not rendered in layout	Only some routes record	Add it to the shared layout
Using a server adapter and assuming script runs server-side	No browser requests	Open the actual page in a browser

Wizard config summary

Wizard field	Value
Integration	`astro`
Env vars	`PUBLIC_HUMANBEHAVIOR_API_KEY`, `PUBLIC_HUMANBEHAVIOR_INGESTION_URL`
Detection	`astro` dependency or `astro.config.*`
Reference files	`src/components/HumanBehavior.astro`, `src/layouts/Layout.astro`

Verify

Restart Astro after env changes.
Open a page that uses the shared layout.
Confirm /api/ingestion/events and /heartbeat (init is not required).
Navigate to another route and interact with an island if present.
Open Replays.

Full checklist: Verify data is flowing.

Astro

On this page