How to Integrate Bolt.new with Segment

Before installing the SDK, you need a Segment Source. A Source represents a single data origin — your web app. Log into app.segment.com, click 'Add Source' (or go to Connections → Sources → Add Source). Search for 'JavaScript' and select 'Javascript (Browser)'. Give it a name matching your app ('My Bolt App' or your actual app name) and click 'Add Source'. After creating the source, click on it to open the source details. Go to Settings → API Keys. You will see a Write Key — copy it. The Write Key looks like a long alphanumeric string. This is the only credential needed for browser-side tracking. It is safe to expose as a VITE_ variable or NEXT_PUBLIC_ variable because it only authorizes writing events to your Segment source — it cannot read your data or access other sources. For production apps, Segment recommends using separate Sources for development and production environments. Create a second source called 'My Bolt App (Dev)' and use its write key in your .env file, reserving the production write key for your deployed app. This prevents development test traffic from appearing in your production analytics. Understand Segment's destination model before proceeding: after events arrive in Segment, nothing goes anywhere until you configure destinations. Go to your Source → Connections → Add Destination to add Mixpanel, Google Analytics, Amplitude, or any of the 300+ available destinations. Segment will forward all future events to configured destinations automatically. This tutorial covers the SDK setup — destination configuration happens in the Segment dashboard.

1// lib/segment.ts
2import { AnalyticsBrowser } from '@segment/analytics-next';
3
4const writeKey = import.meta.env.VITE_SEGMENT_WRITE_KEY as string;
5
6if (!writeKey && import.meta.env.DEV) {
7  console.warn('Segment: VITE_SEGMENT_WRITE_KEY is not set — analytics disabled');
8}
9
10export const analytics = writeKey
11  ? AnalyticsBrowser.load(
12      { writeKey },
13      {
14        integrations: {
15          'Segment.io': {
16            deliveryStrategy: {
17              strategy: 'batching',
18              config: { size: 10, timeout: 5000 },
19            },
20          },
21        },
22      }
23    )
24  : null;
25
26// .env
27// VITE_SEGMENT_WRITE_KEY=YOUR_WRITE_KEY_HERE

Segment's API is built around three core methods that form the foundation of any analytics implementation. Understanding when to use each is essential for producing clean, consistent data. identify(userId, traits) — call this when you know who the user is, typically after login or signup. The first argument is the user's unique ID (from your database — a UUID, not an email). The second argument is an object of user traits: email, name, plan, createdAt. Segment passes these traits to all destinations that support user profiles (Mixpanel people properties, Amplitude user properties, Intercom contact details). Call identify once per session when auth state changes, then reset on logout. track(event, properties) — call this for any user action you want to measure. Event names in Segment follow Title Case convention ('Subscription Upgraded', not 'subscription_upgraded') — this is Segment's recommended style and maps cleanly to destinations that expect specific naming. Properties add context: { plan: 'pro', mrr: 49, billingCycle: 'monthly' }. page(name, properties) — call this on every page navigation. For Vite single-page apps, call page() when your router changes routes. For Next.js App Router, call page() in a usePathname effect. Segment's page call tracks the page name, URL, referrer, and any custom properties you pass. Many Segment destinations use page() to track pageviews automatically. All three methods return a Promise — you can await them if you need confirmation that the event was queued, but usually fire-and-forget is appropriate. The SDK batches events and sends them in groups for efficiency, so individual track() calls do not create individual network requests.

1// lib/analytics.ts
2import { analytics } from './segment';
3
4type Properties = Record<string, string | number | boolean | null>;
5
6export const Analytics = {
7  // Call after user logs in:
8  identify: (userId: string, traits: {
9    email?: string;
10    name?: string;
11    plan?: string;
12    createdAt?: string;
13    [key: string]: unknown;
14  }) => {
15    analytics?.identify(userId, traits);
16  },
17
18  // Call on logout:
19  reset: () => {
20    analytics?.reset();
21  },
22
23  // Generic track call:
24  track: (event: string, properties: Properties = {}) => {
25    analytics?.track(event, properties);
26  },
27
28  // Call on route change:
29  page: (name?: string, properties: Properties = {}) => {
30    analytics?.page(name, properties);
31  },
32
33  // Typed event helpers:
34  signupCompleted: (method: string) =>
35    Analytics.track('Signup Completed', { method }),
36
37  projectCreated: (type: string, template: boolean) =>
38    Analytics.track('Project Created', { project_type: type, template_used: template }),
39
40  subscriptionUpgraded: (fromPlan: string, toPlan: string, mrr: number) =>
41    Analytics.track('Subscription Upgraded', { from_plan: fromPlan, to_plan: toPlan, mrr }),
42
43  exportCompleted: (format: string) =>
44    Analytics.track('Export Completed', { format }),
45};

One of Segment's most powerful features is that you configure where your data goes without writing any integration code. After events arrive in Segment, you connect destinations from the dashboard — and Segment forwards all matching events automatically. To add a destination: go to your Source in the Segment dashboard → Connections → Add Destination. Browse or search for your tool. Popular destinations for Bolt apps: Mixpanel (funnel and retention analytics), Amplitude (product analytics with session replay), Google Analytics 4 (traffic and conversion tracking), Intercom (user messaging triggered by events), and data warehouses like Snowflake or BigQuery for raw data analysis. Each destination has its own configuration. For Mixpanel, you need to enter your Mixpanel Project Token. For Google Analytics 4, you enter your Measurement ID. For data warehouses, you enter connection credentials. Segment's UI guides you through each destination's requirements. Destination filters let you control which events go to which tools. For example, you might send all events to your data warehouse but only send payment events to Intercom for customer messaging. Configure this in the destination settings under Filters → Add Filter. For browser-based destinations (like Google Analytics 4's gtag.js), Segment can load the destination SDK directly without you adding it to your HTML. This 'device-mode' integration loads the third-party script through Segment's SDK, keeping your app's HTML clean. Cloud-mode destinations (like Mixpanel's server-to-server API) receive events server-side through Segment's infrastructure without any client-side SDK loading.

1// components/SegmentTest.tsx (development testing only)
2'use client';
3
4import { Analytics } from '@/lib/analytics';
5
6export function SegmentTest() {
7  if (process.env.NODE_ENV !== 'development') return null;
8
9  const fireTestEvent = () => {
10    Analytics.track('Segment Test Event', {
11      timestamp: new Date().toISOString(),
12      source: 'bolt_preview',
13      test: true,
14    });
15    console.log('Segment test event fired — check Source Debugger');
16  };
17
18  const fireTestIdentify = () => {
19    Analytics.identify('test-user-123', {
20      email: 'test@example.com',
21      name: 'Test User',
22      plan: 'free',
23    });
24    console.log('Segment identify fired — check Source Debugger');
25  };
26
27  return (
28    <div style={{ position: 'fixed', bottom: 16, right: 16, zIndex: 9999 }}>
29      <button onClick={fireTestEvent}>Fire Test Event</button>
30      <button onClick={fireTestIdentify}>Fire Identify</button>
31    </div>
32  );
33}

Some analytics events should be sent from the server rather than the browser. Server-side events are more reliable (not blocked by ad blockers), cannot be tampered with by the client, and can include server-only data (like database IDs assigned after creation). Common server-side events: subscription created (after Stripe webhook confirms payment), account deleted (after database record removal), or any event where you need to guarantee delivery regardless of whether the browser tab is still open. Segment's HTTP Tracking API accepts POST requests to https://api.segment.io/v1/track with Basic Auth (Write Key as username, empty password). The request body matches Segment's standard event format: userId, event, properties, and optional context and timestamp. You can use your same Write Key for server-side calls — but it must be a server-side environment variable (no NEXT_PUBLIC_ prefix) to prevent exposure in client bundles. For Next.js Bolt apps, send server-side events from API routes — typically after database operations succeed. The pattern: receive webhook or form submission, validate and save to database, then send Segment event as the final step. If Segment delivery fails, it should not roll back your database operation — wrap the Segment call in a try/catch and log errors without throwing. Note about Bolt WebContainer: the server-side HTTP Tracking API call (a simple fetch to api.segment.io) should work in the WebContainer preview since it is a standard outbound HTTPS request. However, some complex authentication patterns can behave differently in WebContainers than in production. If you encounter issues, deploy to Netlify to test server-side Segment calls in a proper Node.js environment.

1// lib/segment-server.ts
2const SEGMENT_WRITE_KEY = process.env.SEGMENT_WRITE_KEY;
3
4interface SegmentTrackPayload {
5  userId: string;
6  event: string;
7  properties?: Record<string, unknown>;
8  timestamp?: string;
9  context?: {
10    ip?: string;
11    userAgent?: string;
12    [key: string]: unknown;
13  };
14}
15
16export async function trackServer(
17  payload: SegmentTrackPayload
18): Promise<void> {
19  if (!SEGMENT_WRITE_KEY) {
20    console.warn('Segment server: SEGMENT_WRITE_KEY not set — event not sent');
21    return;
22  }
23
24  try {
25    const response = await fetch('https://api.segment.io/v1/track', {
26      method: 'POST',
27      headers: {
28        'Authorization': `Basic ${Buffer.from(SEGMENT_WRITE_KEY + ':').toString('base64')}`,
29        'Content-Type': 'application/json',
30      },
31      body: JSON.stringify({
32        ...payload,
33        timestamp: payload.timestamp ?? new Date().toISOString(),
34      }),
35    });
36
37    if (!response.ok) {
38      const text = await response.text();
39      console.error('Segment server track failed:', response.status, text);
40    }
41  } catch (error) {
42    // Never throw — analytics failure should not break business logic
43    console.error('Segment server track error:', error);
44  }
45}
46
47export async function identifyServer(
48  userId: string,
49  traits: Record<string, unknown>
50): Promise<void> {
51  if (!SEGMENT_WRITE_KEY) return;
52  try {
53    await fetch('https://api.segment.io/v1/identify', {
54      method: 'POST',
55      headers: {
56        Authorization: `Basic ${Buffer.from(SEGMENT_WRITE_KEY + ':').toString('base64')}`,
57        'Content-Type': 'application/json',
58      },
59      body: JSON.stringify({ userId, traits, timestamp: new Date().toISOString() }),
60    });
61  } catch (error) {
62    console.error('Segment server identify error:', error);
63  }
64}