How to Integrate Bolt.new with Mixpanel

The `mixpanel-browser` package is Mixpanel's official browser-side SDK. It is a pure JavaScript package with no native module dependencies, so it installs and runs cleanly in Bolt's WebContainer. After initialization, the SDK automatically tracks a set of super properties (browser, OS, screen resolution, $current_url) on every event without any additional configuration. Your Mixpanel Project Token is the only credential needed for the browser SDK. Find it in Mixpanel Settings (gear icon bottom-left) → Project Settings → Project Token. It is safe to use as a VITE_ variable or NEXT_PUBLIC_ variable because it only identifies your project for data ingestion — it cannot be used to read or delete your analytics data. Keep your Mixpanel Service Account credentials (for the Data Export API) server-side only. Initialize Mixpanel once in your app's entry point. The init() call accepts your Project Token and an optional config object. Key config options: debug: true enables verbose console logging during development (shows every event being sent), track_pageview: true enables automatic page view tracking (useful for Vite apps; for Next.js with client-side routing, disable this and handle manually), and persistence: 'localStorage' stores the distinct_id across page refreshes (the default and recommended setting). After calling init(), Mixpanel creates an anonymous distinct_id for the current user and stores it in localStorage. All events from this browser session are associated with this anonymous ID until you call mixpanel.identify() with a real user ID. This means analytics data is captured even for logged-out or anonymous users, and the timeline is preserved when an anonymous user later signs up.

1// lib/mixpanel.ts
2import mixpanel from 'mixpanel-browser';
3
4const TOKEN = import.meta.env.VITE_MIXPANEL_TOKEN as string;
5
6let initialized = false;
7
8export function initMixpanel() {
9  if (!TOKEN) {
10    console.warn('Mixpanel: VITE_MIXPANEL_TOKEN is not set');
11    return;
12  }
13  if (initialized) return;
14
15  mixpanel.init(TOKEN, {
16    debug: import.meta.env.DEV,
17    track_pageview: true,
18    persistence: 'localStorage',
19    ignore_dnt: false, // respect Do Not Track header
20  });
21
22  initialized = true;
23}
24
25export function track(
26  eventName: string,
27  properties: Record<string, string | number | boolean> = {}
28) {
29  if (!initialized) return;
30  mixpanel.track(eventName, properties);
31}
32
33export function identify(userId: string, userProps?: Record<string, unknown>) {
34  if (!initialized) return;
35  mixpanel.identify(userId);
36  if (userProps) {
37    mixpanel.people.set(userProps);
38  }
39}
40
41export function reset() {
42  if (!initialized) return;
43  mixpanel.reset();
44}

Mixpanel tracks events against a 'distinct_id' — by default, an anonymous UUID assigned by the SDK. When a user logs in, you need to call mixpanel.identify(userId) to link the anonymous events to the real user account. This is critical for user-level analytics: cohort analysis, retention reports, and per-user funnels all require identified users. The identify() call accepts a string user ID. Use the same permanent user ID from your database (a UUID or auto-increment integer) — not an email address, since users can change emails. Mixpanel will merge the pre-login anonymous events with the identified user profile, creating a complete timeline from first visit through conversion and beyond. After calling identify(), call mixpanel.people.set() to add user properties to their Mixpanel profile. These properties become dimensions for segmentation: show me all sessions by users on the Pro plan, compare retention between users who completed onboarding vs. those who skipped it. People properties sync to the user profile in Mixpanel's People section. Use mixpanel.people.set_once() for properties that should never be overwritten — for example, the user's signup date. Calling set_once('$created', date) on every login won't overwrite the original signup date if it was already set. Use mixpanel.people.set() for mutable properties like plan or last_login that should update. When a user logs out, call mixpanel.reset() to generate a new anonymous distinct_id and clear the stored user state. This prevents subsequent anonymous browsing sessions from being attributed to the previous user.

1// In your auth context — after Supabase auth state change:
2import { identify, track, reset } from '@/lib/mixpanel';
3
4// On sign in:
5identify(user.id, {
6  $email: user.email,
7  $name: user.user_metadata?.full_name ?? '',
8  plan: user.user_metadata?.plan ?? 'free',
9  $created: user.created_at,
10  app_version: import.meta.env.VITE_APP_VERSION ?? '1.0.0',
11});
12track('user_signed_in', {
13  method: session.user.app_metadata?.provider ?? 'email',
14});
15
16// On sign out:
17track('user_signed_out', {});
18reset();
19
20// For incrementing numeric people properties (e.g., login count):
21// import mixpanel from 'mixpanel-browser';
22// mixpanel.people.increment('login_count');

The most valuable Mixpanel setups track a focused set of events that represent actual business outcomes — not every click or hover. A good tracking plan starts with your conversion funnel and then adds the top 5-10 actions that correlate with retention and revenue. Each event should have a descriptive snake_case name that reads like a sentence in past tense: 'project_created', 'file_exported', 'subscription_upgraded', 'feature_enabled'. Properties add context that lets you filter and segment: a 'file_exported' event with format: 'pdf' tells you more than 'file_exported' alone. Mixpanel's super properties feature (mixpanel.register()) sets properties that are automatically attached to every subsequent event. This is useful for properties that apply globally: plan tier, app version, or A/B test variant. Set super properties at login after calling identify() and they persist in localStorage until reset() is called. For events that need precise timing or properties not available at the exact moment of tracking, use mixpanel.time_event('event_name') before the action starts, then call mixpanel.track('event_name', properties) when it completes. Mixpanel automatically adds a $duration property in seconds. This is useful for measuring how long users take to complete flows like onboarding or checkout. One architectural pattern that works well in React: create a centralized analytics.ts file that exports typed event-tracking functions. Instead of calling mixpanel.track() directly in components (which creates tight coupling to Mixpanel), components call analytics.signupCompleted() or analytics.projectCreated(). This makes it trivial to add Amplitude or Segment alongside Mixpanel later.

1// lib/analytics.ts
2import { track } from './mixpanel';
3
4export const analytics = {
5  signupCompleted: (method: 'email' | 'google' | 'github') =>
6    track('signup_completed', { method }),
7
8  onboardingStepCompleted: (step: number, stepName: string) =>
9    track('onboarding_step_completed', { step_number: step, step_name: stepName }),
10
11  onboardingCompleted: (totalSteps: number, timeSpentSeconds: number) =>
12    track('onboarding_completed', {
13      total_steps: totalSteps,
14      time_spent_seconds: timeSpentSeconds,
15    }),
16
17  projectCreated: (projectType: string, templateUsed: boolean) =>
18    track('project_created', { project_type: projectType, template_used: templateUsed }),
19
20  subscriptionUpgraded: (fromPlan: string, toPlan: string, mrr: number) =>
21    track('subscription_upgraded', { from_plan: fromPlan, to_plan: toPlan, mrr }),
22
23  exportCompleted: (format: string, itemCount: number) =>
24    track('export_completed', { format, item_count: itemCount }),
25
26  featureEnabled: (featureName: string) =>
27    track('feature_enabled', { feature_name: featureName }),
28
29  searchPerformed: (query: string, resultsCount: number) =>
30    track('search_performed', { query_length: query.length, results_count: resultsCount }),
31};

Mixpanel's JQL (JavaScript Query Language) Data Export API and the newer Mixpanel Query API allow you to run analytics queries programmatically and display results in your own UI. This is useful for building internal dashboards that show key metrics without requiring team members to have Mixpanel accounts, or for embedding analytics data directly in your admin panel. Mixpanel API access uses Service Account authentication. Create a Service Account in Mixpanel Settings → Service Accounts → Create Service Account. Give it a name and copy the username and secret — the secret is shown only once. Store these as server-side environment variables. The Mixpanel Query API (api.mixpanel.com/api/query/insights) accepts requests structured like Mixpanel Insights queries. You specify the event name, date range, metric (total, unique users, DAU), and optional filters and breakdowns. Responses are JSON objects with time-series data. Important: Mixpanel's query APIs must be called from a server-side Next.js API route, not directly from the browser. The Service Account credentials give read access to all your analytics data and must stay server-side. Additionally, because Mixpanel's API uses HTTP Basic Auth with the service account credentials, calling it from the browser would expose those credentials in client-side code. Note on WebContainer: if you test this API route in the Bolt preview and encounter connection issues, it is likely a WebContainer HTTP constraint affecting the googleapis authentication flow. Deploy to Netlify or Bolt Cloud to test server-side API routes that require multi-step authentication flows.

1// app/api/mixpanel/events/route.ts
2import { NextResponse } from 'next/server';
3
4export async function GET() {
5  const username = process.env.MIXPANEL_SERVICE_ACCOUNT_USERNAME;
6  const secret = process.env.MIXPANEL_SERVICE_ACCOUNT_SECRET;
7  const projectId = process.env.MIXPANEL_PROJECT_ID;
8
9  if (!username || !secret || !projectId) {
10    return NextResponse.json(
11      { error: 'Mixpanel credentials not configured' },
12      { status: 500 }
13    );
14  }
15
16  const credentials = Buffer.from(`${username}:${secret}`).toString('base64');
17  const fromDate = new Date();
18  fromDate.setDate(fromDate.getDate() - 7);
19  const from = fromDate.toISOString().split('T')[0];
20  const to = new Date().toISOString().split('T')[0];
21
22  const events = ['signup_completed', 'project_created', 'subscription_upgraded'];
23
24  try {
25    const results = await Promise.all(
26      events.map(async (eventName) => {
27        const url = new URL('https://data.mixpanel.com/api/2.0/segmentation');
28        url.searchParams.set('project_id', projectId);
29        url.searchParams.set('event', eventName);
30        url.searchParams.set('from_date', from);
31        url.searchParams.set('to_date', to);
32        url.searchParams.set('type', 'general');
33
34        const res = await fetch(url.toString(), {
35          headers: { Authorization: `Basic ${credentials}` },
36        });
37
38        if (!res.ok) throw new Error(`Mixpanel API error: ${res.status}`);
39        const data = await res.json() as { data: { values: Record<string, Record<string, number>> } };
40        const total = Object.values(data.data?.values?.[eventName] ?? {}).reduce(
41          (sum, v) => sum + (v as number),
42          0
43        );
44        return { event: eventName, total };
45      })
46    );
47
48    return NextResponse.json({ results, period: { from, to } });
49  } catch (error: unknown) {
50    const e = error as { message: string };
51    return NextResponse.json({ error: e.message }, { status: 500 });
52  }
53}