Documentation
Recipes

Add FounderHQ to v0

Install the FounderHQ web SDK in a v0 project with one prompt.

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

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.

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

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:

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.

Paste this prompt into v0

Prompt for v0:

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.

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).
  • 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.

Do it by hand instead

  1. Install the package.
npm install @founderhq/events
  1. Add the client component.
"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;
}
  1. Render <FounderHqAnalytics /> once in your root layout.

Want the server side as well? See Add FounderHQ to Next.js.

Let your agent read these docs

Connect the docs 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.

AI agent or LLM? Read this page as markdown

On this page