# Add FounderHQ to v0 (https://www.getfounderhq.com/docs/analytics/recipes/v0)

Paste one prompt into v0 and get working analytics on every page. About
5 minutes.

<Callout title="Before you start">
You need a FounderHQ account and a publishable key. In the app, open
**Sequences → Settings → Event API keys**, create a key for
**Browser/mobile**, and copy it. The full key is shown only once.
</Callout>

v0 builds React and Next.js projects, so this recipe uses the npm package
rather than a script tag.

## 1. Store the key as an environment variable

Open your project's environment settings in v0, or the environment
variables of the Vercel project it deploys to. Add:

```text
NEXT_PUBLIC_FOUNDERHQ_KEY = fhq_pk_XXXX
```

The `NEXT_PUBLIC_` prefix is what lets the browser read the value. This
key is publishable, so a visitor seeing it is expected. Never put a secret
key (`fhq_sk_...`) in a browser.

Add the value to every environment you preview or ship from.

## 2. Paste this prompt into v0

Prompt for v0:

```text
Add FounderHQ analytics to this project.

1. Install the package @founderhq/events.

2. Read the key from process.env.NEXT_PUBLIC_FOUNDERHQ_KEY. Do not paste
   the key value into any file. If the project is not Next.js, rename the
   variable to the prefix my build tool needs and tell me the new name.

3. Detect the project shape, then pick one placement:
   - Next.js App Router: create a client component that calls
     founderhq.init(key) inside a useEffect with an empty dependency array
     and returns null. Render that component once in app/layout.tsx.
   - A plain React app: call founderhq.init(key) once at the app's entry
     point, at module scope.
   Pick one placement only. Never initialize it twice.

4. Only if this app already has sign-in: after a successful sign-in, call
   founderhq.identify with the user's stable database id, and their email
   as a property. Call founderhq.reset() on sign-out. If the app has no
   sign-in, skip this step. Do not add authentication.

5. Do not add any other analytics tool. Do not change analytics tools that
   are already installed.

End state: the app renders one FounderHQ initializer, founderhq.init runs
once with the key from the environment, and pageviews are captured without
any further code.
```

## 3. What the prompt does

- It keeps the key in the environment, and out of your source files.
- It makes the agent check whether the project is App Router or plain
  React, because `init` runs in the browser only.
- It pins the App Router answer to a client component, which is the same
  pattern as [Quickstart: Web (npm)](/analytics/getting-started/quickstart-web-npm).
- It adds `identify` only when your app already knows who the person is.

After `init` runs, FounderHQ captures pageviews, page leaves, sessions,
clicks, rage clicks, dead clicks, outbound clicks, scroll depth, and Core
Web Vitals for you. Single-page navigations count as pageviews.

## 4. Do it by hand instead

1. Install the package.

```npm
npm install @founderhq/events
```

2. Add the client component.

```tsx
"use client";

import { useEffect } from "react";
import { founderhq } from "@founderhq/events";

export function FounderHqAnalytics() {
  useEffect(() => {
    founderhq.init(process.env.NEXT_PUBLIC_FOUNDERHQ_KEY!);
  }, []);
  return null;
}
```

3. Render `<FounderHqAnalytics />` once in your root layout.

Want the server side as well? See
[Add FounderHQ to Next.js](/analytics/recipes/nextjs).

## 5. Let your agent read these docs

Connect the [docs MCP server](/analytics/ai-resources/mcp-server), then name it
in your prompt. Your agent then reads these pages while it writes the code.

## Verify

1. Open the preview or the deployed site, and load a page.
2. In FounderHQ, open **Sequences → Events**.
3. You see a `$pageview` for that page, with its channel.
4. Move to a second page. A second `$pageview` arrives.

Events can take a few seconds to appear. The SDK batches them.

## Troubleshoot

### Nothing appears in Events

Check that the variable exists in the environment you opened. A value
added to production is not present in a preview deployment until you add
it there too.

### Requests to `/i/v2/e` return 401 or 403

The key is wrong, or the domain is not allowed. Preview deployments get
their own domain. Add it to **Allowed origins** on the key, in
**Sequences → Settings → Event API keys**.