{"id":11336,"library":"mixpanel-react-native","title":"Mixpanel React Native SDK","description":"Mixpanel React Native SDK is the official open-source library for integrating Mixpanel analytics into React Native applications, supporting both iOS and Android platforms. It acts as a wrapper around Mixpanel's native SDKs and enables robust offline tracking capabilities. The current stable version is 3.3.0, with frequent minor and patch releases to include enhancements, security updates, and bug fixes, indicating an active development cadence. A key differentiator is its direct wrapping of native SDKs, ensuring consistency with native Mixpanel features, and its explicit support for data persistence via `async-storage` to handle offline scenarios reliably. It's designed for React Native v0.6+ and ships with TypeScript types.","status":"active","version":"3.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/mixpanel/mixpanel-react-native","tags":["javascript","mixpanel","react","native","ios","android","analytics","tracking","sdk","typescript"],"install":[{"cmd":"npm install mixpanel-react-native","lang":"bash","label":"npm"},{"cmd":"yarn add mixpanel-react-native","lang":"bash","label":"yarn"},{"cmd":"pnpm add mixpanel-react-native","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for data persistence and offline tracking. Starting from v3.2.0, it is a peer dependency.","package":"@react-native-async-storage/async-storage","optional":false}],"imports":[{"note":"The primary class for instantiating the Mixpanel client. The library is primarily consumed via ES Modules.","wrong":"const Mixpanel = require('mixpanel-react-native').Mixpanel;","symbol":"Mixpanel","correct":"import { Mixpanel } from 'mixpanel-react-native';"},{"note":"Type import for the Mixpanel client instance, useful for TypeScript projects.","symbol":"MixpanelInstance","correct":"import type { MixpanelInstance } from 'mixpanel-react-native';"},{"note":"Type import for event properties, allowing strong typing of tracking data in TypeScript.","symbol":"MixpanelProperties","correct":"import type { MixpanelProperties } from 'mixpanel-react-native';"}],"quickstart":{"code":"import React, { useEffect } from 'react';\nimport { Button, SafeAreaView, Text, View } from 'react-native';\nimport { Mixpanel } from 'mixpanel-react-native';\n\nconst projectToken = process.env.MIXPANEL_PROJECT_TOKEN ?? 'YOUR_MIXPANEL_PROJECT_TOKEN'; // Replace with your Mixpanel project token\nconst trackAutomaticEvents = false;\n\nconst mixpanel = new Mixpanel(projectToken, trackAutomaticEvents);\n\nexport default function App() {\n  useEffect(() => {\n    mixpanel.init();\n  }, []);\n\n  const trackEvent = (eventName) => {\n    mixpanel.track(eventName, { source: 'React Native App', time: new Date().toISOString() });\n    console.log(`Tracked event: ${eventName}`);\n  };\n\n  const identifyUser = () => {\n    const userId = 'user123'; // Replace with actual user ID\n    mixpanel.identify(userId);\n    mixpanel.people.set({ '$first_name': 'Test', '$last_name': 'User', 'plan': 'Free' });\n    console.log(`Identified user: ${userId}`);\n  };\n\n  return (\n    <SafeAreaView style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>\n      <Text style={{ fontSize: 24, marginBottom: 20 }}>Mixpanel React Native Demo</Text>\n      <View style={{ gap: 10 }}>\n        <Button title=\"Track 'App Loaded'\" onPress={() => trackEvent('App Loaded')} />\n        <Button title=\"Track 'Button Clicked'\" onPress={() => trackEvent('Button Clicked')} />\n        <Button title=\"Identify User\" onPress={identifyUser} />\n        <Button title=\"Reset Mixpanel\" onPress={() => mixpanel.reset()} />\n      </View>\n    </SafeAreaView>\n  );\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure `@react-native-async-storage/async-storage` is installed in your project: `npm install @react-native-async-storage/async-storage`.","message":"As 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.","severity":"breaking","affected_versions":">=3.2.0"},{"fix":"Upgrade to v3.0.9 or a newer version to resolve the distinct ID bug. `npm install mixpanel-react-native@latest`","message":"Versions prior to v3.0.9 had a bug where the distinct ID could sometimes be `<nil>`, leading to inconsistent tracking data.","severity":"gotcha","affected_versions":"<3.0.9"},{"fix":"Upgrade Xcode to version 13.2.1 or newer. If an upgrade is not possible, refer to the workaround mentioned in GitHub issue #43.","message":"When using Xcode versions between 12.5 and 13.2.1, a known Swift compile issue could occur.","severity":"gotcha","affected_versions":"Xcode >=12.5 <13.2.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `@react-native-async-storage/async-storage` and run `pod install` for iOS: `npm install @react-native-async-storage/async-storage && cd ios && pod install`","cause":"The `@react-native-async-storage/async-storage` dependency is missing or not correctly linked, which is required for data persistence.","error":"TypeError: Cannot read property 'getItem' of undefined"},{"fix":"Ensure 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`).","cause":"Common React Native setup issue, often related to the Metro bundler or app registration.","error":"Invariant Violation: 'main' has not been registered. This can happen if:"},{"fix":"Ensure `mixpanel.init()` is called once, typically in a `useEffect` hook for functional components or `componentDidMount` for class components, before any tracking methods are invoked.","cause":"Attempting to use Mixpanel tracking methods (`track`, `identify`, etc.) before calling `mixpanel.init()`.","error":"Error: Mixpanel has not been initialized. Call init() before tracking."}],"ecosystem":"npm"}