Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Mixpanel
✓ import { Mixpanel } from 'mixpanel-react-native';
✗ const Mixpanel = require('mixpanel-react-native').Mixpanel;
The primary class for instantiating the Mixpanel client. The library is primarily consumed via ES Modules.
MixpanelInstance
✓ import type { MixpanelInstance } from 'mixpanel-react-native';
Type import for the Mixpanel client instance, useful for TypeScript projects.
MixpanelProperties
✓ import type { MixpanelProperties } from 'mixpanel-react-native';
Type import for event properties, allowing strong typing of tracking data in TypeScript.
This example demonstrates basic Mixpanel integration in a React Native app, including initialization, tracking custom events with properties, identifying a user, setting user profile properties, and resetting the Mixpanel instance.
import React, { useEffect } from 'react';
import { Button, SafeAreaView, Text, View } from 'react-native';
import { Mixpanel } from 'mixpanel-react-native';
const projectToken = process.env.MIXPANEL_PROJECT_TOKEN ?? 'YOUR_MIXPANEL_PROJECT_TOKEN'; // Replace with your Mixpanel project token
const trackAutomaticEvents = false;
const mixpanel = new Mixpanel(projectToken, trackAutomaticEvents);
export default function App() {
useEffect(() => {
mixpanel.init();
}, []);
const trackEvent = (eventName) => {
mixpanel.track(eventName, { source: 'React Native App', time: new Date().toISOString() });
console.log(`Tracked event: ${eventName}`);
};
const identifyUser = () => {
const userId = 'user123'; // Replace with actual user ID
mixpanel.identify(userId);
mixpanel.people.set({ '$first_name': 'Test', '$last_name': 'User', 'plan': 'Free' });
console.log(`Identified user: ${userId}`);
};
return (
<SafeAreaView style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
<Text style={{ fontSize: 24, marginBottom: 20 }}>Mixpanel React Native Demo</Text>
<View style={{ gap: 10 }}>
<Button title="Track 'App Loaded'" onPress={() => trackEvent('App Loaded')} />
<Button title="Track 'Button Clicked'" onPress={() => trackEvent('Button Clicked')} />
<Button title="Identify User" onPress={identifyUser} />
<Button title="Reset Mixpanel" onPress={() => mixpanel.reset()} />
</View>
</SafeAreaView>
);
}
Debug
Known issues
breakingAs of v3.2.0, `@react-native-async-storage/async-storage` became a peer dependency. Your project must now explicitly install and manage this dependency. This change was implemented to avoid conflicts with frameworks like Expo.fixEnsure `@react-native-async-storage/async-storage` is installed in your project: `npm install @react-native-async-storage/async-storage`.
affects: >=3.2.0
gotchaVersions prior to v3.0.9 had a bug where the distinct ID could sometimes be `<nil>`, leading to inconsistent tracking data.fixUpgrade to v3.0.9 or a newer version to resolve the distinct ID bug. `npm install mixpanel-react-native@latest`
affects: <3.0.9
gotchaWhen using Xcode versions between 12.5 and 13.2.1, a known Swift compile issue could occur.fixUpgrade Xcode to version 13.2.1 or newer. If an upgrade is not possible, refer to the workaround mentioned in GitHub issue #43.
affects: Xcode >=12.5 <13.2.1
Errors
Common errors & fixes
TypeError: Cannot read property 'getItem' of undefined
The `@react-native-async-storage/async-storage` dependency is missing or not correctly linked, which is required for data persistence.
fixInstall `@react-native-async-storage/async-storage` and run `pod install` for iOS: `npm install @react-native-async-storage/async-storage && cd ios && pod install`
Invariant Violation: 'main' has not been registered. This can happen if:
Common React Native setup issue, often related to the Metro bundler or app registration.
fixEnsure your `index.js` or `index.ts` file correctly registers the root component. Also, try clearing the Metro bundler cache (`npm start --reset-cache`) and reinstalling node modules (`rm -rf node_modules && npm install`).
Error: Mixpanel has not been initialized. Call init() before tracking.
Attempting to use Mixpanel tracking methods (`track`, `identify`, etc.) before calling `mixpanel.init()`.
fixEnsure `mixpanel.init()` is called once, typically in a `useEffect` hook for functional components or `componentDidMount` for class components, before any tracking methods are invoked.
Audit
Dependencies
@react-native-async-storage/async-storagerequiredRequired for data persistence and offline tracking. Starting from v3.2.0, it is a peer dependency.