Mixpanel Browser SDK

Common errors

• ReferenceError: mixpanel is not defined

  cause The Mixpanel SDK script has not loaded, or the `mixpanel` object was not correctly imported or initialized before being accessed. This often happens if an `import` statement is missing or `mixpanel.init()` is called too late.
  fix Ensure that `import mixpanel from 'mixpanel-browser';` is at the top of your module and `mixpanel.init('YOUR_TOKEN');` is called before any other Mixpanel methods. If using a `<script>` tag, ensure it loads before your application code.

• TypeError: mixpanel.track is not a function

  cause The `mixpanel` object might not be the correct instance or was not properly initialized. This can occur if a CommonJS `require` statement is used in a browser context where an ESM `import` is expected, or if `mixpanel.init()` failed.
  fix Verify that `import mixpanel from 'mixpanel-browser';` is correctly used and `mixpanel.init('YOUR_TOKEN');` has been successfully executed. Check the browser console for any earlier initialization errors.

• Module not found: Error: Can't resolve 'mixpanel-browser'

  cause The `mixpanel-browser` package is not installed in the project's `node_modules` directory, or there's a typo in the import path.
  fix Run `npm install --save mixpanel-browser` or `yarn add mixpanel-browser` to install the package. Double-check the import statement for any spelling mistakes.

• CORS error (Cross-Origin Resource Sharing) when sending data to Mixpanel

  cause This usually indicates an issue with your website's server configuration (e.g., if you're proxing requests) or if the Mixpanel API host does not match your project's data residency (US, EU, India).
  fix Check your network requests in the browser's developer console for specific CORS error details. Ensure your `api_host` configuration matches your Mixpanel project's data residency (e.g., `api-eu.mixpanel.com` for EU). If using a proxy, verify its CORS configuration.

Warnings

• gotcha Client-side tracking with Mixpanel can be unreliable due to ad blockers or 'Do Not Track' browser settings, potentially leading to a loss of 30-50% of user events. Server-side tracking or using a proxy is recommended for improved reliability.
  Fix: For critical events, consider implementing server-side tracking. For client-side tracking, investigate setting up a proxy server to mitigate ad blocker impact. Ensure users are informed about data collection as per privacy regulations.
• breaking Session Replay for cross-origin iframes (introduced in v2.77.0) requires explicit domain allowlisting via the `record_allowed_iframe_origins` configuration option for security reasons. Without proper allowlisting, content from these iframes will not be captured. Both parent and child iframes need to specify allowed origins.
  Fix: When initializing Mixpanel, configure `record_allowed_iframe_origins` with an array of allowed domain origins. Example: `mixpanel.init('YOUR_TOKEN', { record_sessions_percent: 100, record_allowed_iframe_origins: ['https://embedded-widget.example.com'] });`
• breaking The Session Recording Masking API was updated in v2.74.0, introducing `record_mask_all_text` (defaulting to `true`) and `record_unmask_text_selector`. If your application previously relied on default unmasked text, it might now be masked, requiring explicit configuration to reveal specific elements.
  Fix: Review your session recording configuration. To unmask specific text elements, use `record_unmask_text_selector`. To disable global text masking, set `record_mask_all_text: false` (use with caution for sensitive data). Example: `mixpanel.init('TOKEN', { record_mask_all_text: true, record_unmask_text_selector: '.unmask-this-content' });`
• gotcha The `disable_persistence` option (enhanced in v2.69.0) now strictly prevents modification of `sessionStorage` and `IndexedDB`. If your application inadvertently relied on less strict persistence disabling, you might observe altered data storage behavior for device IDs and super properties.
  Fix: Ensure that `disable_persistence: true` is used only when genuinely intending to prevent *all* client-side storage by Mixpanel, understanding it disables features like anonymous-to-identified user tracking and super properties. Verify data flow and user identity stitching under this configuration.
• gotcha The `mixpanel-browser` package is distinct from the server-side `mixpanel` Node.js library. Confusing the two can lead to incorrect imports and unexpected behavior, especially concerning browser-specific features like session replay.
  Fix: Always use `mixpanel-browser` for client-side web applications and `mixpanel` (the Node.js package) for server-side implementations. Ensure correct import syntax (`import` for `mixpanel-browser`) and initialize with browser-appropriate configurations.
• gotcha The Network Recording plugin for Session Replay (v2.76.0) is in beta, and captured data will not appear in the Mixpanel UI until the feature is explicitly enabled within your Mixpanel project settings. Documentation for UI enablement is often separate from SDK release notes.
  Fix: No direct SDK fix required; acknowledge that visibility in the Mixpanel UI depends on backend enablement. Refer to Mixpanel's official documentation for instructions on enabling beta features in your project settings.

Install

• npm install mixpanel-browser npm
• yarn add mixpanel-browser yarn
• pnpm add mixpanel-browser pnpm

Imports

• mixpanel
  wrong:

  const mixpanel = require('mixpanel-browser');

  correct:

  import mixpanel from 'mixpanel-browser';

  This is the primary import for the client-side Mixpanel SDK. While the package specifies Node.js engines, it is predominantly used in browser environments via bundlers. CommonJS `require` is generally incorrect for the browser-targeted build; use ESM `import` statements.
• mixpanel (core-only)

  import mixpanel from 'mixpanel-browser/src/loaders/loader-module-core';

  Use this specific path to import the core SDK without the `mixpanel-recorder` SDK. This is useful for reducing bundle size if session replay functionality is not required. The export is still the default `mixpanel` object.
• mixpanel (async modules)

  import mixpanel from 'mixpanel-browser/src/loaders/loader-module-with-async-modules';

  This loader allows for asynchronously loading session recording and targeting bundles, which can help optimize initial page load performance.
• mixpanel.flags

  mixpanel.flags.loadFlags();

  The `mixpanel.flags` object for Feature Flags is available directly on the `mixpanel` instance after initialization. TypeScript types for this subsystem were added in v2.72.0.

Quickstart

Initializes Mixpanel with common configuration options, identifies a user, tracks a custom event, sets user profile properties, and demonstrates basic feature flag usage.

import mixpanel from 'mixpanel-browser';

const MIXPANEL_TOKEN = process.env.MIXPANEL_TOKEN ?? 'YOUR_MIXPANEL_PROJECT_TOKEN';

// Initialize Mixpanel with autocapture, session recording, and debug mode
mixpanel.init(MIXPANEL_TOKEN, {
  autocapture: true, // Automatically track common user interactions
  track_pageview: true, // Automatically track page views
  record_sessions_percent: 100, // Record 100% of user sessions for replay
  record_heatmap_data: true, // Enable heatmap, rage click, and dead click collection
  persistence: 'localStorage', // Use localStorage for more reliable persistence than cookies
  debug: true, // Enable debug logs in the console
  // Example of cross-origin iframe recording allowlist for security (since v2.77.0)
  // record_allowed_iframe_origins: ['https://embedded-widget.example.com'],
});

// Identify a user after they log in or sign up
mixpanel.identify('USER_ID_123', {
  name: 'John Doe',
  email: 'john.doe@example.com',
  plan: 'Enterprise'
});

// Track a custom event with properties
mixpanel.track('Signed Up', {
  'Signup Type': 'Referral',
  'Source Page': '/pricing'
});

// Track a page view explicitly (if not using track_pageview: true in init)
// mixpanel.track('Page View', {
//   'Page Title': document.title,
//   'Page URL': window.location.href
// });

// Set or update user profile properties
mixpanel.people.set({
  '$last_login': new Date().toISOString(),
  'Subscription Status': 'Active'
});

// Example of using feature flags (requires feature flags configured in Mixpanel)
mixpanel.flags.whenReady().then(() => {
  if (mixpanel.flags.enabled('new-feature-flag')) {
    console.log('New feature is enabled for this user!');
  } else {
    console.log('New feature is NOT enabled for this user.');
  }
});