Bug report widget for React Native and Expo

This quickstart adds Mushi Mushi’s shake-to-report and floating bug button to your iOS or Android app.

Works for bare React Native CLI apps and Expo apps (managed-with-dev-client or bare). Peer dependency is React Native ≥ 0.72; this quickstart targets 0.82+ with the New Architecture as the recommended baseline.

Get your project ID and API key

The SDK needs two values from a Mushi Mushi project.

• Fastest: run npx mushi-mushi in your app’s folder. It signs you in through the browser, creates or picks a project, installs the SDK and writes both values to .env.local.
• By hand: create a free account  (no card) and create a project. The panel that opens shows the project ID and an API key that starts with mushi_. Copy the key now: it is shown once. You can mint another under Set up → Test it → Generate API key.
• Self-hosting? Your own console gives you the same two values. See Self-hosting.

They replace YOUR_PROJECT_ID and YOUR_PUBLIC_API_KEY in step 2. On Expo the wizard names them EXPO_PUBLIC_MUSHI_PROJECT_ID and EXPO_PUBLIC_MUSHI_API_KEY.

1. Install

# React Native CLI
npm install @mushi-mushi/react-native @react-native-async-storage/async-storage
cd ios && bundle exec pod install && cd ..
 
# Expo
npx expo install @mushi-mushi/react-native @react-native-async-storage/async-storage

To enable shake-to-report, also install expo-sensors. On a bare RN CLI project, wire up Expo modules first (one-time):

# Bare RN CLI only — Expo apps already have this
npx install-expo-modules@latest
npm install expo-sensors
cd ios && bundle exec pod install && cd ..
 
# Expo
npx expo install expo-sensors

2. Mount the provider

import { MushiProvider } from '@mushi-mushi/react-native'
 
export default function App() {
  return (
    <MushiProvider
      projectId="YOUR_PROJECT_ID"
      apiKey="YOUR_PUBLIC_API_KEY"
      config={{
        widget: { trigger: 'both' },        // 'shake' | 'button' | 'both' | 'manual'
        capture: { console: true, network: true },
      }}
    >
      <RootNavigator />
    </MushiProvider>
  )
}

<MushiProvider> mounts the floating bug button automatically (unless you set trigger: 'manual'), opens the bottom-sheet report form on tap or shake, and attaches the last 100 console logs and last 50 network requests to every report.

Optional native modules

Three packages are optional. The SDK picks each one up when it is installed:

The SDK loads them with a plain require() inside try/catch, which Metro treats as optional (transformer.allowOptionalDependencies, on in Expo and React Native’s default Metro config). If your Metro config turns that off, or you would rather the SDK never load anything itself, pass the modules in:

import type { ReactNode } from 'react'
import { MushiProvider } from '@mushi-mushi/react-native'
import NetInfo from '@react-native-community/netinfo'
import * as ViewShot from 'react-native-view-shot'
import * as ExpoSensors from 'expo-sensors'
 
export function AppWithMushi({ children }: { children: ReactNode }) {
  return (
    <MushiProvider
      projectId="YOUR_PROJECT_ID"
      apiKey="YOUR_PUBLIC_API_KEY"
      netInfo={NetInfo}
      viewShot={ViewShot}
      expoSensors={ExpoSensors}
    >
      {children}
    </MushiProvider>
  )
}

A module you pass in always wins. Versions 0.21–0.23 needed a postinstall patch for these (__require errors in Metro); releases with this fix need none.

3. Verify

Run your app on a simulator or a device, tap the bug button, type a description, and submit. The report should appear in the Mushi Mushi admin console within a couple of seconds, showing the SDK that sent it (@mushi-mushi/react-native and its version).

If nothing arrives:

• Confirm apiKey is a Mushi Mushi project key (it starts with mushi_, like every Mushi Mushi key) with the report:write scope, not the Supabase service-role key.
• Confirm <MushiProvider> is at the root of the component tree, above any NavigationContainer.
• iOS release builds must use HTTPS for the Mushi Mushi endpoint (the default).